Two announcement rows on the Today screen, each opening a bundled Markdown document rendered natively — no web view, no new dependency. Nineteen commits across two phases, reviewed by six agents in three rounds.
body evaluation. One document, read twice, with “no body touches the disk” stated but not held.specs/OVERVIEW.md said Done in the table and Planned — Q1–Q28 in the detail section; CLAUDE.md gained a rule saying a seeded UI-test launch removes its keys, which this branch's own pin breaks.main's tip, which is one Makefile-only commit from the branch point. Measuring them also surfaced a fourth pre-existing failure no tally had counted.Ready to push
Ready to push. Four review agents (reuse, quality, efficiency, spec/docs/tests) ran over
the branch after two earlier design-critic passes. Every finding is fixed or recorded: the
headline structural fix removes a double file read and a prose-held invariant, and both
must-fix items — a self-contradicting specs/OVERVIEW.md and a
CLAUDE.md rule this branch's own code broke — are corrected.
make test-quick passes at 1,717 marks with zero failures and zero new compiler
warnings, verified on an independent run. The six failures across the long UI suites are
measured to reproduce at main's tip, in a worktree holding none of this
branch's code.
Two things remain owner work and neither blocks the push: the three bundled documents are drafts written from the specs, and two instruction paths in them (the iOS share-sheet favourites steps, the macOS System Settings path) have never been walked on hardware.
2b220f06 [doc]: the pre-push review's documentation fixes a2dfb4a7 [bug]: the pre-push review's fixes to the announcement views 760f8369 [doc]: changelog for phase 2 of today-announcements 86f61c71 [bug]: the design-critic review's fixes to phase 2 06943260 [feat]: the phase 2 verification pass ae567929 [feat]: the journeys that asserted the empty message assert the row ca21c04a [feat]: the getting-started guide, and the row that replaces the empty message b1d71308 [doc]: changelog for phase 1 of today-announcements bcc63977 [bug]: the review's fixes to the announcement row's first phase 17f63fcc [feat]: UI journeys for the release-note row and the Settings route ce81ea89 [feat]: an About section in Settings that opens the release notes 14e19c39 [feat]: the release-note row on Today, its sheet, and version 0.7.0 2431a504 [feat]: draw a bundled document natively, with its earlier versions under it f7f9939c [feat]: the last-seen version, per device, with the seeded launch pinned fad5b4e8 [feat]: announcement rules and the bundled-document catalog e73b9448 specs/OVERVIEW: add today-announcements as Planned 3bc17458 specs/today-announcements: approved task list 90498d1e specs/today-announcements: approved smolspec and decision log 2b4698f3 CLAUDE.md: cross-launch state defaults to UserDefaults, marker files by exception The app can now tell you what a new version changed, and can explain itself to someone who has captured nothing yet. Two kinds of announcement appear on the Today screen as a single row that looks like an ordinary entry row, with the app icon where a cover would be. Tapping one opens a sheet holding a short document that ships inside the app.
Both documents also live in a new About section in Settings, so nothing you have read is ever out of reach.
Before this, a new release was silent and an empty library explained nothing. The feature adds no server, no download and no schema change — the documents are files compiled into the app, and the only thing remembered is one version string per device, which deliberately does not sync.
UserDefaults key per device; comparing it
to the app's version is the whole trigger.The feature is four layers with one direction of travel. Pure rules
(TodayAnnouncements) decide which row to show from booleans about the
library; a small @Observable state object
(AnnouncementSeenState) owns the one UserDefaults key and a catalog
of readable documents; a splitter (MarkdownBlocks) turns text into blocks; and
SwiftUI views draw them. No view or view model holds a ModelContext, and nothing
in the feature writes to the store.
body touches the disk.drawsEmptyLibraryMessage(branch:announcement:)), so they cannot disagree.UserDefaults and Bundle are
parameters, so tests hand over a throwaway suite and a throwaway bundle rather than mocking.The trigger is string inequality between CFBundleShortVersionString and a
stored value, so a downgrade counts as a change. Ordering for the previous-versions list is
numeric per dotted component with a missing component read as zero, which is why
0.10.0 sorts above 0.9.0 where a string compare would not.
The gate that decides whether a row exists is readability, not presence: a bundled file
that reads empty is refused by the same predicate on Today and in Settings. That bar is what
makes emptyLibrarySection safe to key off the gated answer rather than the display
branch — keying off the branch would give a blank screen in a build with no readable guide,
and a unit test now fails that rewrite.
Nothing in AsterismCore moved: no schema, no frozen snapshot, no readiness
marker, no archive generation. The only cross-cutting change is
MARKETING_VERSION 1.0 → 0.7.0 across all ten target configurations, since the
extensions' version must match the app's.
Asterism/Asterism/Announcements/AnnouncementCatalog.swift
Why it matters. Performance and API surface. The readability filter read each document in full and discarded it, while the document view re-read the same file on every body evaluation. Keeping the text makes every gate a lookup and lets AnnouncementSeenState stop exposing a Bundle.
What to look at. BundledAnnouncements.catalog(in:), AnnouncementCatalog.text(for:)
Asterism/Asterism/ViewModels/TodayAnnouncements.swift
Why it matters. Correctness, user-visible. Writing the condition as branch != .emptyLibrary passes every test in the repo and gives a blank empty-library screen in a build with no readable guide.
What to look at. drawsEmptyLibraryMessage(branch:announcement:), called from TodayView.emptyLibrarySection
Asterism/AsterismTests/BundledAnnouncementTests.swift
Why it matters. Closes a defect class. The splitter has no lazy continuation, so a hard-wrapped list item renders broken - which shipped in phase 1's release note. The original guard caught an indented wrap and silently passed a flush-left one.
What to look at. bundledDocumentsStayInsideTheSubset, theSubsetCheckCatchesAHardWrappedItem
Asterism/Asterism/ContentView.swift
Why it matters. Correctness, and the store has no undo. Keyed by the generation alone, a first publication landing before the modifier installed would skip the store for the whole launch.
What to look at. onChange(of: model.snapshotGeneration, initial: true); launchSeenState()
Asterism/Asterism/Announcements/AnnouncementCardButton.swift
Why it matters. Hit target. The two originals put padding on opposite sides of the Button; outside leaves an icon-less card with a tap area far smaller than the 44pt card that draws it.
What to look at. AnnouncementCardButton, used by TodayAnnouncementRow and AnnouncementDocumentView
Asterism/Asterism.xcodeproj/project.pbxproj
Why it matters. This is the feature's trigger: the rule compares CFBundleShortVersionString against bundled note filenames. The extensions' version must match the app's.
What to look at. 10 XCBuildConfiguration blocks across 5 targets
Every document is owner-written, so the subset can stay strict and the fidelity problems a general renderer solves do not arise. Extracting the owner's existing WebKit renderer was measured at 5,000–7,000 lines of Swift plus ~2,500 of CSS and JavaScript and two dependencies. swift-markdown is kept as the named fallback if the subset becomes a burden.
None of the four marker-file reasons applies. This also corrected CLAUDE.md, which claimed the project had zero UserDefaults usage — it had five @AppStorage keys and no weighed decision behind the claim.
A faked entry would carry Teach and Resolve actions and enter search, the day plan, the duplicate plan and every entry count. The priced consequence is that the row copies TodayEntryRow's layout and must be maintained in both places.
onDismiss takes no argument and runs after the binding is nil, so it cannot say which item was dismissed — and only a release note stores. The alternative, a second @State holding the dismissed item, is more code for the same result.
Clearing would put a release-note row on every content-bearing fixture and shift rows under a large number of existing journeys. The cost, recorded rather than fixed, is that the “key absent” state becomes untestable end to end.
It is CPU with no I/O once the catalog holds the text, and moving it behind .task would flash the “could not be read” arm on the first frame before the task runs.
| Severity | Area | Finding | Resolution |
|---|---|---|---|
| major | AnnouncementCatalog / AnnouncementDocumentView | The catalog read every bundled document in full to decide readability and discarded the text, while the document view re-read the same file on every body evaluation - contradicting the 'no body touches the disk' principle stated in the catalog's own doc comment. | The catalog keeps the text it reads; the view became a lookup; AnnouncementSeenState.bundle was removed entirely, dropping the (catalog, bundle) pair that travelled through three initializers behind a warning comment at each hop. |
| major | specs/OVERVIEW.md | The table row said Done while the detail section still read 'Planned - smolspec and ten tasks approved. Q1-Q28', so the file whose job is to be the index reported the feature as never built. | Detail line brought in step with the table and pointed at verification-run.md; the status cell now carries its evidence the way neighbouring rows do. |
| major | CLAUDE.md | The rule this branch added says a seeded UI-test launch removes the keys it can change; this branch's own pinLastSeenVersion writes one instead. CLAUDE.md stated a rule the newest code in the repo breaks. | The rule now states both cases - removing where absence is neutral, pinning where removal would itself change what the fixture shows - and cites Q14. |
| major | BundledAnnouncementTests | The guard protecting every bundled document hand-copied MarkdownBlocks' trailing-trim and list-marker rules. Adding a bullet marker to the parser would leave the guard silently blind and green - the failure mode that shipped a broken release note in phase 1. | trailingTrimmed and isListMarkerLine promoted to internal on MarkdownBlocks; the test calls them. The proof test still fails on both flush-left and indented wraps. |
| minor | AnnouncementSheet / SettingsView | The sheet reached for SettingsView.releaseNotesTitle to name its own title bar, importing a View's detail into an unrelated view. | Both titles moved onto the model as documentTitle; SettingsView reads it. |
| minor | ContentView | Two adjacent onChange(of: model.snapshotGeneration) handlers, neither with initial: true, so a first publication landing before the modifier installed would skip the silent store for that launch. | Merged into one handler with initial: true, after checking both calls are idempotent at generation 0. |
| minor | Test helpers | withThrowawayDefaults and withBundle(containing:) were defined in one suite and open-coded in another, one of them repeating an Issue.record sentence verbatim. | Lifted into a shared AnnouncementTestSupport enum used by both suites. |
| minor | TodayAnnouncementRow / MarkdownDocumentView | The feature spelled its own card button twice, differing only in the leading icon and the identifier. | One AnnouncementCardButton serves both, with padding inside the label so an icon-less card cannot hold a tap area smaller than the card drawn (Q38). |
| minor | AnnouncementCatalog | '.md' was spelled four ways, including a dropLast(3) magic number three lines from the literal it depends on. | A fileExtension constant now drives all of them; the literal appears nowhere in the file. |
| minor | ContentView sheet | sheet(item:) whose body was an if-let with no else, so a nil document would present an empty sheet with no Done button and, on macOS, no dismiss gesture. | The lookup moved inside the sheet, which always presents with its Done button and reuses the single 'could not be read' arm. |
| minor | AnnouncementSeenState | hasNoteForCurrentVersion was production API whose only caller was a test. | Deleted; the test asserts the underlying expression directly. |
| minor | Q11 silent store | The silent-store wiring has no end-to-end coverage and cannot get any: the seeded-launch pin means no launch leaves the key absent, and the override can set a value but never remove one. | Recorded as accepted in Q36 with the reasoning, rather than threading a test-only removing sentinel through a launch sequence that already carries a declaration-order hazard. Also written into docs/agent-notes/testing.md for whoever writes the next journey. |
| minor | Decision log completeness | Three real divergences had no record: the sheet titling itself by document kind rather than version, a seventh accessibility identifier beyond the spec's enumerated six, and Q32's closing sentence describing a re-read that the fix had removed. | Q34, Q35 and Q38 added; Q32 amended, including replacing its 'size check' guidance - the bound to watch is the count of notes, not their size, and a size check cannot tell whitespace from prose. |
Source: local run at 2026-09-21T12:00:00+10:00 · snapshot 2b220f06
Baseline: none
Execution: passed · JUnit: none · Coverage: none · Baseline: absent
Coverage scope: as the project configures it
The test runner could not be detected.
Derived by declaration name, from the diff (no baseline run).
Files that import a changed file on the left, changed files in the centre, files a changed file imports on the right. Snapshot working-tree against base 1e30f17152831817122744ba2d021121e7d441ce.
Click to expand.
diff --git a/Asterism/Asterism.xcodeproj/project.pbxproj b/Asterism/Asterism.xcodeproj/project.pbxprojindex 763b22f9..cb8ebc2a 100644--- a/Asterism/Asterism.xcodeproj/project.pbxproj+++ b/Asterism/Asterism.xcodeproj/project.pbxproj@@ -599,7 +599,7 @@ "@executable_path/Frameworks", "@executable_path/../../Frameworks", );- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.Asterism.dev.ShareExtension; PRODUCT_NAME = "$(TARGET_NAME)"; SKIP_INSTALL = YES;@@ -628,7 +628,7 @@ "@executable_path/Frameworks", "@executable_path/../../Frameworks", );- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.Asterism.ShareExtension; PRODUCT_NAME = "$(TARGET_NAME)"; SKIP_INSTALL = YES;@@ -658,7 +658,7 @@ "@executable_path/../../../../Frameworks", ); MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.Asterism.dev.ShareExtensionMac; PRODUCT_NAME = "$(TARGET_NAME)"; REGISTER_APP_GROUPS = YES;@@ -689,7 +689,7 @@ "@executable_path/../../../../Frameworks", ); MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.Asterism.ShareExtensionMac; PRODUCT_NAME = "$(TARGET_NAME)"; REGISTER_APP_GROUPS = YES;@@ -732,7 +732,7 @@ LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks"; "LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks"; MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.Asterism.dev; PRODUCT_NAME = "$(TARGET_NAME)"; REGISTER_APP_GROUPS = YES;@@ -781,7 +781,7 @@ LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks"; "LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks"; MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.Asterism; PRODUCT_NAME = "$(TARGET_NAME)"; REGISTER_APP_GROUPS = YES;@@ -945,7 +945,7 @@ GENERATE_INFOPLIST_FILE = YES; IPHONEOS_DEPLOYMENT_TARGET = 26.0; MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.AsterismTests; PRODUCT_NAME = "$(TARGET_NAME)"; SDKROOT = auto;@@ -972,7 +972,7 @@ GENERATE_INFOPLIST_FILE = YES; IPHONEOS_DEPLOYMENT_TARGET = 26.0; MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.AsterismTests; PRODUCT_NAME = "$(TARGET_NAME)"; SDKROOT = auto;@@ -998,7 +998,7 @@ GENERATE_INFOPLIST_FILE = YES; IPHONEOS_DEPLOYMENT_TARGET = 26.0; MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.AsterismUITests; PRODUCT_NAME = "$(TARGET_NAME)"; SDKROOT = auto;@@ -1024,7 +1024,7 @@ GENERATE_INFOPLIST_FILE = YES; IPHONEOS_DEPLOYMENT_TARGET = 26.0; MACOSX_DEPLOYMENT_TARGET = 26.5;- MARKETING_VERSION = 1.0;+ MARKETING_VERSION = 0.7.0; PRODUCT_BUNDLE_IDENTIFIER = me.nore.ig.AsterismUITests; PRODUCT_NAME = "$(TARGET_NAME)"; SDKROOT = auto;
diff --git a/Asterism/Asterism/Announcements/AnnouncementCardButton.swift b/Asterism/Asterism/Announcements/AnnouncementCardButton.swiftnew file mode 100644index 00000000..2656e593--- /dev/null+++ b/Asterism/Asterism/Announcements/AnnouncementCardButton.swift@@ -0,0 +1,70 @@+import ConstellationKit+import SwiftUI++/// The card the announcements are tapped through (`today-announcements` Q1,+/// Q3): a serif title on the repo's row card, with an optional leading slot.+///+/// Two surfaces draw it — Today's announcement row, which fills the leading+/// slot with the app icon, and the previous-versions list under a release note,+/// which leaves it empty. They were the same construct written twice, down to+/// the card modifiers' order, so the shape lives here and each caller supplies+/// the two things that actually differ: what goes in the leading slot, and the+/// identifier a UI journey finds it by.+///+/// **It is not `TodayEntryRow`.** The row's resemblance to an entry row is+/// deliberate and separate (Q1); this is the announcement feature's own button+/// and nothing in the Today list is built from it.+struct AnnouncementCardButton<Leading: View>: View {+ private let title: String+ private let identifier: String+ private let action: () -> Void+ private let leading: Leading++ init(+ title: String,+ identifier: String,+ action: @escaping () -> Void,+ @ViewBuilder leading: () -> Leading+ ) {+ self.title = title+ self.identifier = identifier+ self.action = action+ self.leading = leading()+ }++ var body: some View {+ Button(action: action) {+ HStack(alignment: .center, spacing: 0) {+ leading+ Text(title)+ .font(AsterismTypography.serifRowTitle)+ .lineLimit(1)+ .truncationMode(.tail)+ .foregroundStyle(AsterismColors.primaryText)+ Spacer()+ }+ // Inside the label, so the whole card is the hit target rather+ // than the text inside it. `TodayEntryRow` pads outside its+ // buttons because it has several of them side by side; this card+ // has one, and a 44-point minimum around a single line of text is+ // only honoured if the padding is part of what is tapped.+ .padding(.vertical, 10)+ .padding(.horizontal, 12)+ .frame(maxWidth: .infinity, alignment: .leading)+ .contentShape(Rectangle())+ }+ .buttonStyle(.plain)+ .frame(minHeight: AsterismLayout.minHitTarget)+ .constellationCard()+ .accessibilityIdentifier(identifier)+ .accessibilityLabel(title)+ }+}++extension AnnouncementCardButton where Leading == EmptyView {+ /// A card with nothing in its leading slot, which is what the+ /// previous-versions list draws.+ init(title: String, identifier: String, action: @escaping () -> Void) {+ self.init(title: title, identifier: identifier, action: action) { EmptyView() }+ }+}
diff --git a/Asterism/Asterism/Announcements/AnnouncementCatalog.swift b/Asterism/Asterism/Announcements/AnnouncementCatalog.swiftnew file mode 100644index 00000000..839d9f8f--- /dev/null+++ b/Asterism/Asterism/Announcements/AnnouncementCatalog.swift@@ -0,0 +1,191 @@+import Foundation++/// One bundled announcement document, named by what it is rather than by where+/// it sits (`today-announcements` Q9).+///+/// The scheme is a **filename prefix** because the project's synchronized folder+/// groups copy resources flat into the bundle root: a `Documents/` subdirectory+/// exists in the repository and not in the built bundle, so the directory cannot+/// carry the meaning and the name has to.+nonisolated enum AnnouncementDocument: Equatable, Hashable {+ /// `release-notes-<version>.md`, one file per released version.+ case releaseNote(version: String)+ /// `getting-started.md`, the shared guide.+ case gettingStarted+ /// `getting-started-mac.md`, shown in place of the shared guide on the Mac+ /// and nowhere else (Q16).+ case gettingStartedMac++ /// The resource name, which is the filename without its extension.+ var resourceName: String {+ switch self {+ case .releaseNote(let version): "\(AnnouncementCatalog.releaseNotePrefix)\(version)"+ case .gettingStarted: "getting-started"+ case .gettingStartedMac: "getting-started-mac"+ }+ }++ /// The file this document is bundled as. The extension is spelled once, in+ /// ``AnnouncementCatalog/fileExtension``.+ var filename: String { "\(resourceName).\(AnnouncementCatalog.fileExtension)" }++ /// The title over the rendered document: the **kind** of document, not the+ /// row's `Version <number>` (Q34).+ ///+ /// It lives on the document because both routes into one need it — the+ /// sheet's navigation title and Settings' row and destination — and a title+ /// owned by one of the two views is a detail the other has to import.+ var documentTitle: String {+ switch self {+ case .releaseNote: "Release notes"+ case .gettingStarted, .gettingStartedMac: "Getting started"+ }+ }+}++/// What this build has bundled: which release notes, and which getting-started+/// variants.+///+/// A pure value built from a list of filenames, so the rules above it can be+/// asserted without a bundle. ``load(from:)`` is the thin wrapper that asks a+/// real one.+nonisolated struct AnnouncementCatalog: Equatable {+ static let releaseNotePrefix = "release-notes-"+ /// The one extension a bundled document has, spelled once: the resource+ /// names, the bundle listing and the bundle lookup all derive from it.+ static let fileExtension = "md"++ /// Every bundled release-note version, newest first by numeric comparison of+ /// dotted integers (Q10).+ let releaseNoteVersions: [String]+ let hasGettingStarted: Bool+ let hasGettingStartedMac: Bool++ /// The text of each document, where the catalog was built from a bundle it+ /// had to read anyway (Q32) — empty for a catalog built from names alone.+ ///+ /// Keeping what was already read is what makes ``text(for:)`` a lookup, so+ /// no `body` evaluation reopens a file the launch had open.+ private let texts: [AnnouncementDocument: String]++ /// A catalog from filenames alone: **pure and unfiltered**, which is what+ /// the rules above it are asserted against. It holds no text, so+ /// ``text(for:)`` answers nil for every document in it.+ init(filenames: [String]) {+ self.init(documents: filenames.compactMap { Self.document(forFilename: $0) }, texts: [:])+ }++ /// A catalog from documents whose text has already been read — the shape+ /// ``BundledAnnouncements/catalog(in:)`` builds, so the one pass over the+ /// bundle serves both the gates and the renderer (Q32).+ init(texts: [AnnouncementDocument: String]) {+ self.init(documents: Array(texts.keys), texts: texts)+ }++ private init(documents: [AnnouncementDocument], texts: [AnnouncementDocument: String]) {+ var versions: [String] = []+ var gettingStarted = false+ var gettingStartedMac = false+ for document in documents {+ switch document {+ case .releaseNote(let version): versions.append(version)+ case .gettingStarted: gettingStarted = true+ case .gettingStartedMac: gettingStartedMac = true+ }+ }+ releaseNoteVersions = TodayAnnouncements.sortedNewestFirst(versions)+ hasGettingStarted = gettingStarted+ hasGettingStartedMac = gettingStartedMac+ self.texts = texts+ }++ /// The text to draw for a document, or nil where this catalog holds none —+ /// a catalog built from names, or a document this build does not bundle.+ func text(for document: AnnouncementDocument) -> String? { texts[document] }++ /// Which document a bundled file is, or nil where the name is not one of+ /// ours.+ ///+ /// A `release-notes-` file whose version is not dotted integers is **not** a+ /// document (Q26): reading a suffix as zero would make `1.1-beta` collide+ /// with `1.1`, so such a file is ignored, never listed and never produces a+ /// row.+ static func document(forFilename filename: String) -> AnnouncementDocument? {+ let suffix = ".\(fileExtension)"+ guard filename.hasSuffix(suffix) else { return nil }+ let name = String(filename.dropLast(suffix.count))+ switch name {+ case AnnouncementDocument.gettingStarted.resourceName: return .gettingStarted+ case AnnouncementDocument.gettingStartedMac.resourceName: return .gettingStartedMac+ default:+ guard name.hasPrefix(releaseNotePrefix) else { return nil }+ let version = String(name.dropFirst(releaseNotePrefix.count))+ guard TodayAnnouncements.isDottedIntegers(version) else { return nil }+ return .releaseNote(version: version)+ }+ }++ /// The newest bundled note, which is what Settings' Release notes row opens.+ var newestReleaseNoteVersion: String? { releaseNoteVersions.first }++ /// The versions listed under a shown note: every *other* bundled one,+ /// newest first.+ func otherReleaseNoteVersions(than version: String) -> [String] {+ releaseNoteVersions.filter { $0 != version }+ }++ /// The getting-started document this platform shows (Q16). The Mac variant+ /// where one is bundled, the shared guide otherwise — and the Mac only: an+ /// iPad shares the phone's share sheet and its steps.+ func gettingStartedDocument(isMac: Bool) -> AnnouncementDocument? {+ if isMac, hasGettingStartedMac { return .gettingStartedMac }+ return hasGettingStarted ? .gettingStarted : nil+ }+}++/// The bundle side of the catalog: listing the `.md` resources, and reading one.+///+/// Deliberately thin — everything that can be decided about a filename is+/// decided in ``AnnouncementCatalog``, which no bundle is needed to test.+nonisolated enum BundledAnnouncements {+ /// What this bundle has, **as documents that read**: a file is in the+ /// catalog only when its text comes back non-empty, and the catalog keeps+ /// the text it read.+ ///+ /// Q29 closed here, in task 8. A listing alone cannot tell a bundled+ /// document from a bundled empty one, so the Today gate — which consults the+ /// catalog — drew a row for a document that then rendered "This document+ /// could not be read", where Settings, which read the text, hid its row. The+ /// two now ask the same question, and they ask it **once**: the catalog is+ /// built when ``AnnouncementSeenState`` is constructed, so no `body`+ /// evaluation touches the disk — neither Today's hot path nor the document+ /// view, which draws the text this pass kept rather than reopening the file.+ /// Reading them costs one pass over a handful of small files at launch,+ /// which is what the documents are; they cannot change while the app is+ /// running.+ static func catalog(in bundle: Bundle = .main) -> AnnouncementCatalog {+ var texts: [AnnouncementDocument: String] = [:]+ let paths = bundle.paths(+ forResourcesOfType: AnnouncementCatalog.fileExtension, inDirectory: nil)+ for path in paths {+ let filename = URL(fileURLWithPath: path).lastPathComponent+ guard let document = AnnouncementCatalog.document(forFilename: filename),+ let text = text(for: document, in: bundle)+ else { continue }+ texts[document] = text+ }+ return AnnouncementCatalog(texts: texts)+ }++ /// The document's text, or nil when it is missing, unreadable or empty —+ /// the three states a Settings row is hidden for.+ static func text(for document: AnnouncementDocument, in bundle: Bundle = .main) -> String? {+ guard let url = bundle.url(+ forResource: document.resourceName,+ withExtension: AnnouncementCatalog.fileExtension),+ let text = try? String(contentsOf: url, encoding: .utf8),+ !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty+ else { return nil }+ return text+ }+}
diff --git a/Asterism/Asterism/Announcements/Documents/getting-started-mac.md b/Asterism/Asterism/Announcements/Documents/getting-started-mac.mdnew file mode 100644index 00000000..d021355f--- /dev/null+++ b/Asterism/Asterism/Announcements/Documents/getting-started-mac.md@@ -0,0 +1,175 @@+# Getting started++Asterism keeps a record of what you read on the web. You send a page to it+from Safari's Share menu, and it files that page as a note — a chapter of a+work, on the day you read it, with anything you want to say about it.++There is no account to make and nothing to sign up for. Your library lives on+this Mac, and syncs to your other devices through iCloud.++## Turn the Share menu extension on first++Asterism has no browser of its own, so everything starts in Safari. Its Share+menu extension is listed in System Settings, and turning it on is a step the+app cannot take for you — it cannot even tell whether you have taken it.++1. Open **System Settings**, then **General**, then **Login Items & Extensions**.+2. Find **Sharing** in the list of extensions and open it.+3. Make sure **Asterism** is on.+4. Back in Safari, check that Asterism is in the Share menu, and drag it up the list if you want it first.++## Capture a page++1. Finish reading a page in Safari.+2. Open the Share menu — the toolbar button, or **File** then **Share** — and choose **Asterism**.+3. Asterism reads the page and shows you what it will file it as: the work, the chapter, and the note's own title.+4. Type a note if you have something to say. The field is ready for you as soon as the window opens, and it is optional.+5. Click the up or down arrow to rate the chapter, if you want to. Clicking the arrow again clears it.+6. Click the checkmark to save.++The window closes and the note is in your library. If Asterism is already+running, the capture appears in it within a few seconds; otherwise it is there+the next time you open the app.++On the Mac, Asterism works from what the Share menu hands it: the page's+address and, usually, its title. It does not read the page itself. So a site+whose title Asterism cannot make sense of will ask you to type one, under+**Title (required)**, rather than working it out. On the phone it reads a+little more of the page and can sometimes do better.++If the page is one you have already captured, the window opens on the note you+made last time instead, headed with the date you noted it and the words+**editing existing entry**. It saves with the same checkmark as a first+capture. Sharing the same chapter again is how you add to a note rather than+how you make a second one.++A page from a site Asterism has never seen is marked **New site — title saved,+teach later in app**: the capture is kept exactly as it came, and you teach+the site when you are back in the app. That is the next section.++If your library cannot be opened for some reason, the capture is not lost. The+window says **Saved for later**, and the page is added the next time you open+Asterism.++## Teach a site++Most sites put the name of the work and the number of the chapter into every+page title, in the same shape every time. Teaching is showing Asterism that+shape once, for one site. After that, every page you capture from that site —+and every page you captured from it before — is filed as a chapter of a work.++An entry from a site that has not been taught keeps its raw page title and+carries an amber **Teach** button. That is expected, not a fault. Today also+carries a banner counting how many entries are waiting.++1. On Today, click the **Teach** button on one of those entries.+2. Asterism shows the captured title, cut into segments you can click.+3. Click the segment that names the work until it is marked **W**, and the segment that gives the chapter until it is marked **C**. Everything else is marked with a cross and ignored.+4. Read the two lines underneath — **Work will be named** and **Chapter will be named** — and the preview of every entry the rule will touch.+5. Click **Teach**.++Use the scissors on a segment to work inside it when a delimiter falls in the+wrong place, and **Suggest rule** if you would rather be given a starting+point and correct it. Nothing is written until you click **Teach**, and+cancelling changes nothing at all.++Teaching reaches backwards. Every entry already captured from that site is+re-read through the new rule, and the works it names are created as they are+needed. A chapter title you set by hand is never overwritten, and an entry the+rule cannot make sense of keeps what it has and stays on the list of things+needing attention.++Not every site is a site with chapters. If the pages you capture are articles+that stand on their own, use **Treat every page as an article** at the foot of+the teaching screen.++A site can be taught again at any time, and Settings has a **Sites** screen+listing every site your library knows, with the same route into teaching.++## Today++Today is one day at a time. The strip across the top is the week; click a day+to move to it, the chevrons to change week, and the date range above the strip+to come back to today. There is no limit in either direction: past weeks are+what you have read, future weeks are what is due.++The day holds up to three sections.++- **Releasing** lists the works due to release on that day. A work appears here only while it is ongoing and you are reading it.+- **Catching up** lists the works you are behind on, and is absent entirely when there is nothing to list.+- **Noted** lists what you captured on that day.++Select an entry to open it beside the list. Amber buttons on a row are things+waiting for you: **Teach** on an entry from an untaught site, **Resolve**+where two records look like the same thing. The banners above the list count+the same work and filter the list down to it.++The search field searches every day at once, not only the day on screen.+Press **Command-F** to reach it.++## Works++Works is everything you are reading, however long ago you read it.++The funnel in the toolbar holds the sort order — **Newest first**, **Oldest+first**, **A to Z**, **Z to A** — a **Group by series** switch, and filters on+type, tag, site, series,+creator, work status, reading status and release days. Whatever you have+filtered on shows as a row of pills you can clear.++A work carries a status of its own — **Ongoing**, **Finished** or **On+hiatus** — and a reading status of yours: **Reading**, **Catching up**,+**Finished** or **Abandoned**. A work you have abandoned is dimmed in the+list; one you are catching up on is not.++Open a work to give it a cover, a type, release days, creators and their+roles, a place in a series, and links to other works. Release days are what+puts a work in Today's **Releasing** section, and they only apply while the+work is ongoing and you are reading it.++The toolbar also reaches the **Series** and **Creators** lists, and **New+Work** — **Command-N** — for something you want to track before you have+captured anything from it. At the bottom of the list, **Unattached Notes**+holds the captures that belong to no work yet — it is hidden while a search or+a filter is on, because nothing in it can be searched or filtered.++## Stats++Stats counts notes, not pages: a note is counted on the day it was first+captured, and re-reading something does not move it.++The four tiles at the top are your lifetime totals and the totals for the+period on screen. Under them, **Week**, **Month** and **All time** choose the+period. In Week and Month the chevrons move through it a week or a month at a+time, and clicking the period's name jumps to a date; All time has neither,+because there is nothing on either side of it.++The chart is notes per day, or per month over all time. Click a bar to see+that day broken down by work — over All time a bar opens that month instead.+Under the chart, **Most read works this week** and **Most read sites this+week** rank the period you are looking at, named after it. Both are absent+when the period holds no notes.++## Around the Mac app++Asterism opens as one window with the three lists in its sidebar. Settings is+a window of its own, from the sidebar's **Settings** row or **Command-comma**.+The Mac remembers which list and which row you were on and comes back to them.++A few things worth knowing by name.++- **Command-1**, **Command-2** and **Command-3** select Today, Works and Stats.+- **Command-F** puts the cursor in the list's search field, and **Control-Command-S** shows or hides the sidebar.+- **Command-N** makes a new work, and **Shift-Command-E** exports the work or the note you have open as Markdown. It is greyed out on Stats, and whenever nothing is open.+- Chapter and work links open in your default browser.++Settings holds **Sites**, **Work types** and **Creator roles** — the+vocabularies your library uses — and **Backup**, which writes your whole+library to a file through the ordinary save panel and reads one back through+the open panel. This guide and the release notes are under **About**, so+neither is ever out of reach.++Asterism syncs through your own iCloud account, to your devices only. It works+without iCloud too; you simply get one library per device instead of one+library. On a device that has just joined, lists say they are arriving from+iCloud rather than saying they are empty.
diff --git a/Asterism/Asterism/Announcements/Documents/getting-started.md b/Asterism/Asterism/Announcements/Documents/getting-started.mdnew file mode 100644index 00000000..d6ef1bb8--- /dev/null+++ b/Asterism/Asterism/Announcements/Documents/getting-started.md@@ -0,0 +1,160 @@+# Getting started++Asterism keeps a record of what you read on the web. You send a page to it+from Safari's share sheet, and it files that page as a note — a chapter of a+work, on the day you read it, with anything you want to say about it.++There is no account to make and nothing to sign up for. Your library lives on+this device, and syncs to your other devices through iCloud.++## Put Asterism in your share sheet favourites++Asterism has no browser of its own, so everything starts in Safari. The share+sheet's row of apps leads with your favourites; until you make Asterism one of+them, it sits behind **More** at the end of that row. Making it a favourite is+a step the app cannot take for you, and it cannot tell whether you have taken+it.++1. Open any page in Safari and tap the share button.+2. Scroll the row of apps along to its end and tap **More**.+3. Tap **Edit**, turn Asterism on, and add it to your favourites.+4. Drag it towards the front of the row, so it is one tap away next time.++## Capture a page++1. Finish reading a page in Safari and tap the share button.+2. Tap **Asterism**.+3. Asterism reads the page title and shows you what it will file the page as: the work, the chapter, and the note's own title.+4. Type a note if you have something to say. The field is ready for you as soon as the sheet opens, and it is optional.+5. Tap the up or down arrow to rate the chapter, if you want to. Tapping the arrow again clears it.+6. Tap the checkmark to save.++The sheet closes and the note is in your library. Nothing else is asked of+you: the work and the chapter come from the site's own rule, which is the next+section.++If the page is one you have already captured, the sheet opens on the note you+made last time instead, headed with the date you noted it and the words+**editing existing entry**. It saves with the same checkmark as a first+capture. Sharing the same chapter again is how you add to a note rather than+how you make a second one.++Two things can happen that are worth recognising. A page from a site Asterism+has never seen is marked **New site — title saved, teach later in app**: the+capture is kept exactly as it came, and you teach the site when you are back+in the app. A page whose title Asterism cannot read at all asks you to type+one, under **Title (required)**.++If your library cannot be opened for some reason, the capture is not lost. The+sheet says **Saved for later**, and the page is added the next time you open+Asterism.++## Teach a site++Most sites put the name of the work and the number of the chapter into every+page title, in the same shape every time. Teaching is showing Asterism that+shape once, for one site. After that, every page you capture from that site —+and every page you captured from it before — is filed as a chapter of a work.++An entry from a site that has not been taught keeps its raw page title and+carries an amber **Teach** pill. That is expected, not a fault. Today also+carries a banner counting how many entries are waiting.++1. On Today, tap the **Teach** pill on one of those entries.+2. Asterism shows the captured title, cut into segments you can tap.+3. Tap the segment that names the work until it is marked **W**, and the segment that gives the chapter until it is marked **C**. Everything else is marked with a cross and ignored.+4. Read the two lines underneath — **Work will be named** and **Chapter will be named** — and the preview of every entry the rule will touch.+5. Tap **Teach**.++Use the scissors on a segment to work inside it when a delimiter falls in the+wrong place, and **Suggest rule** if you would rather be given a starting+point and correct it. Nothing is written until you tap **Teach**, and+cancelling changes nothing at all.++Teaching reaches backwards. Every entry already captured from that site is+re-read through the new rule, and the works it names are created as they are+needed. A chapter title you set by hand is never overwritten, and an entry the+rule cannot make sense of keeps what it has and stays on the list of things+needing attention.++Not every site is a site with chapters. If the pages you capture are articles+that stand on their own, use **Treat every page as an article** at the foot of+the teaching screen.++A site can be taught again at any time, and Settings has a **Sites** screen+listing every site your library knows, with the same route into teaching.++## Today++Today is one day at a time. The strip across the top is the week; tap a day to+move to it, the chevrons to change week, and the date range above the strip to+come back to today. There is no limit in either direction: past weeks are what+you have read, future weeks are what is due.++The day holds up to three sections.++- **Releasing** lists the works due to release on that day. A work appears here only while it is ongoing and you are reading it.+- **Catching up** lists the works you are behind on, and is absent entirely when there is nothing to list.+- **Noted** lists what you captured on that day.++Tap an entry to open it. Amber pills on a row are things waiting for you: a+**Teach** pill on an entry from an untaught site, a **Resolve** pill where two+records look like the same thing. The banners above the list count the same+work and filter the list down to it.++The search field searches every day at once, not only the day on screen.++## Works++Works is everything you are reading, however long ago you read it.++The funnel in the toolbar holds the sort order — **Newest first**, **Oldest+first**, **A to Z**, **Z to A** — a **Group by series** switch, and filters on+type, tag, site, series,+creator, work status, reading status and release days. Whatever you have+filtered on shows as a row of pills you can clear.++A work carries a status of its own — **Ongoing**, **Finished** or **On+hiatus** — and a reading status of yours: **Reading**, **Catching up**,+**Finished** or **Abandoned**. A work you have abandoned is dimmed in the+list; one you are catching up on is not.++Open a work to give it a cover, a type, release days, creators and their+roles, a place in a series, and links to other works. Release days are what+puts a work in Today's **Releasing** section, and they only apply while the+work is ongoing and you are reading it.++The toolbar also reaches the **Series** and **Creators** lists, and **New+Work** for something you want to track before you have captured anything from+it. At the bottom of the list, **Unattached Notes** holds the captures that+belong to no work yet — it is hidden while a search or a filter is on, because+nothing in it can be searched or filtered.++## Stats++Stats counts notes, not pages: a note is counted on the day it was first+captured, and re-reading something does not move it.++The four tiles at the top are your lifetime totals and the totals for the+period on screen. Under them, **Week**, **Month** and **All time** choose the+period. In Week and Month the chevrons move through it a week or a month at a+time, and tapping the period's name jumps to a date; All time has neither,+because there is nothing on either side of it.++The chart is notes per day, or per month over all time. Tap a bar to see that+day broken down by work — over All time a bar opens that month instead. Under+the chart, **Most read works this week** and **Most read sites this week**+rank the period you are looking at, named after it. Both are absent when the+period holds no notes.++## Everything else++Settings holds **Sites**, **Work types** and **Creator roles** — the+vocabularies your library uses — and **Backup**, which exports your whole+library to a file and reads one back. This guide and the release notes are+under **About**, so neither is ever out of reach.++Asterism syncs through your own iCloud account, to your devices only. It works+without iCloud too; you simply get one library per device instead of one+library. On a device that has just joined, lists say they are arriving from+iCloud rather than saying they are empty.
diff --git a/Asterism/Asterism/Announcements/Documents/release-notes-0.7.0.md b/Asterism/Asterism/Announcements/Documents/release-notes-0.7.0.mdnew file mode 100644index 00000000..07e576ae--- /dev/null+++ b/Asterism/Asterism/Announcements/Documents/release-notes-0.7.0.md@@ -0,0 +1,34 @@+# Version 0.7.0++Asterism can now tell you what a release changed. This is the first of+those notes, and the reason you are reading it.++## Announcements on Today++A note like this one appears as a single row at the top of Today when+you open a version you have not seen yet. Tap it to read it, then tap+**Done** — the row goes away and does not come back for that version.+Nothing is sent anywhere: each device remembers what it has shown you,+and that memory does not sync.++A reader with nothing captured yet gets a **Getting started** row in the+same place instead, explaining how to capture a page, how to teach a+site, and what the three tabs are for.++Both documents stay reachable from **Settings**, under *About*, so+nothing you have read is ever out of reach.++## Also in this release++- **Today** replaces Recent: one day at a time, with the works due to release on it beside the notes you took on it, and a week strip to move between days.+- **Catching up** joins the reading statuses, with a section of its own on Today for the stories you are behind on.+- **Covers**: works can carry a cover picture, cropped where you want it, shown on every row and on the work page.+- **Creators and roles**, with credits on a work and a creator page of their own.+- **Series and related works**, so a work can name its place in a series and its links to other works.+- **Characters and places** extracted from your notes, reviewed by you before anything is written.++## What this version does not do++Only the note for the version you are running is announced. Earlier+notes are listed at the bottom of each note, and every one of them is+also in Settings.
diff --git a/Asterism/Asterism/Announcements/MarkdownBlocks.swift b/Asterism/Asterism/Announcements/MarkdownBlocks.swiftnew file mode 100644index 00000000..e8e044b1--- /dev/null+++ b/Asterism/Asterism/Announcements/MarkdownBlocks.swift@@ -0,0 +1,170 @@+import Foundation++/// One drawable piece of a bundled document (`today-announcements` Decision 1).+///+/// The subset is fixed and small because every document is written by the+/// owner: headings, paragraphs, one-level lists and an image on a line of its+/// own. Anything else is carried through as the literal text it was written as,+/// so a document that strays outside the subset is legible rather than lost.+nonisolated enum MarkdownBlock: Equatable {+ /// `#` to `###`, with the marker stripped.+ case heading(level: Int, text: String)+ /// Consecutive non-empty lines, joined with a space.+ case paragraph(String)+ /// `- ` or `* ` items, one level.+ case unorderedList([String])+ /// `1. ` items, one level. The numbers drawn are 1…n whatever the source+ /// wrote, which is what "ordered lists numbered from 1" means.+ case orderedList([String])+ /// `` alone on its line.+ case image(alt: String, asset: String)+}++/// The pure splitter from a document's text to its blocks.+///+/// A block outside the subset — a table, a code fence, a block quote, a nested+/// list item, raw HTML — is not detected at all: its lines fall through to the+/// paragraph rule and are drawn as the literal text they are.+nonisolated enum MarkdownBlocks {+ static func blocks(from text: String) -> [MarkdownBlock] {+ var blocks: [MarkdownBlock] = []+ var paragraph: [String] = []+ var unordered: [String] = []+ var ordered: [String] = []++ func flushParagraph() {+ guard !paragraph.isEmpty else { return }+ blocks.append(.paragraph(paragraph.joined(separator: " ")))+ paragraph = []+ }+ func flushUnordered() {+ guard !unordered.isEmpty else { return }+ blocks.append(.unorderedList(unordered))+ unordered = []+ }+ func flushOrdered() {+ guard !ordered.isEmpty else { return }+ blocks.append(.orderedList(ordered))+ ordered = []+ }+ func flushAll() {+ flushParagraph()+ flushUnordered()+ flushOrdered()+ }++ for rawLine in text.split(separator: "\n", omittingEmptySubsequences: false) {+ // Trailing whitespace only: a line's *leading* whitespace is what+ // tells a nested list item from a top-level one, and an+ // out-of-subset line keeps its indentation because it is drawn+ // literally.+ let line = trailingTrimmed(String(rawLine))+ if line.trimmingCharacters(in: .whitespaces).isEmpty {+ flushAll()+ continue+ }+ if let heading = heading(in: line) {+ flushAll()+ blocks.append(heading)+ continue+ }+ if let image = image(in: line) {+ flushAll()+ blocks.append(image)+ continue+ }+ if let item = unorderedItem(in: line) {+ flushParagraph()+ flushOrdered()+ unordered.append(item)+ continue+ }+ if let item = orderedItem(in: line) {+ flushParagraph()+ flushUnordered()+ ordered.append(item)+ continue+ }+ flushUnordered()+ flushOrdered()+ paragraph.append(line)+ }+ flushAll()+ return blocks+ }++ // MARK: - The line rules++ /// A line with its trailing whitespace removed, which is the only trimming+ /// the splitter does before a rule looks at the line: *leading* whitespace+ /// is what tells a nested list item from a top-level one.+ ///+ /// Internal rather than private so the guard that holds the bundled+ /// documents to this subset can ask the splitter instead of copying it —+ /// a copy stops agreeing the moment a rule here moves, silently and green+ /// (`BundledAnnouncementTests`).+ static func trailingTrimmed(_ line: String) -> String {+ var line = line+ while let last = line.last, last == " " || last == "\t" { line.removeLast() }+ return line+ }++ /// Whether a line opens a list item under either list rule, which is what+ /// "a hard-wrapped item" is measured against. Internal for+ /// ``trailingTrimmed(_:)``'s reason: add a marker to the rules below and the+ /// guard sees it, rather than passing while it stops looking.+ static func isListMarkerLine(_ line: String) -> Bool {+ unorderedItem(in: line) != nil || orderedItem(in: line) != nil+ }++ /// `#`, `##` or `###` followed by a space. `####` and a `#` with no space+ /// after it are outside the subset and fall through to the paragraph rule.+ private static func heading(in line: String) -> MarkdownBlock? {+ var level = 0+ var rest = Substring(line)+ while rest.first == "#", level < 4 {+ level += 1+ rest = rest.dropFirst()+ }+ guard (1...3).contains(level), rest.first == " " else { return nil }+ let text = rest.trimmingCharacters(in: .whitespaces)+ guard !text.isEmpty else { return nil }+ return .heading(level: level, text: text)+ }++ /// `` and nothing else on the line. An image inside a+ /// sentence is inline, which the subset does not cover, so it stays literal.+ private static func image(in line: String) -> MarkdownBlock? {+ guard line.hasPrefix(" else { return nil }+ let alt = body[body.startIndex..<separator.lowerBound]+ let asset = body[separator.upperBound...].trimmingCharacters(in: .whitespaces)+ // An alt text holding its own `]` is not a shape this subset parses, and+ // a nameless asset is not a reference at all.+ guard !asset.isEmpty, !alt.contains("]") else { return nil }+ return .image(alt: alt.trimmingCharacters(in: .whitespaces), asset: asset)+ }++ /// `- ` or `* ` at the start of the line. An indented item is a nested one,+ /// which the subset does not cover.+ private static func unorderedItem(in line: String) -> String? {+ guard line.hasPrefix("- ") || line.hasPrefix("* ") else { return nil }+ let text = String(line.dropFirst(2)).trimmingCharacters(in: .whitespaces)+ return text.isEmpty ? nil : text+ }++ /// `<digits>. ` at the start of the line. The digits are read and discarded:+ /// the list draws 1…n.+ private static func orderedItem(in line: String) -> String? {+ var rest = Substring(line)+ var digits = 0+ while let first = rest.first, first.isASCII, first.isNumber {+ digits += 1+ rest = rest.dropFirst()+ }+ guard digits > 0, rest.hasPrefix(". ") else { return nil }+ let text = rest.dropFirst(2).trimmingCharacters(in: .whitespaces)+ return text.isEmpty ? nil : text+ }+}
diff --git a/Asterism/Asterism/Announcements/MarkdownDocumentView.swift b/Asterism/Asterism/Announcements/MarkdownDocumentView.swiftnew file mode 100644index 00000000..7834d533--- /dev/null+++ b/Asterism/Asterism/Announcements/MarkdownDocumentView.swift@@ -0,0 +1,236 @@+import ConstellationKit+import SwiftUI++/// A bundled document, drawn with the app's own typography and colours+/// (`today-announcements` Decision 1).+///+/// Native views rather than a web view: they take Dynamic Type, the light and+/// dark appearances and the app's face without a stylesheet, and the splitter+/// behind them is a pure function with tests of its own.+struct MarkdownDocumentView: View {+ let blocks: [MarkdownBlock]++ var body: some View {+ VStack(alignment: .leading, spacing: 14) {+ // By index: two identical paragraphs in one document are two+ // blocks, and the value cannot tell them apart.+ ForEach(Array(blocks.enumerated()), id: \.offset) { _, block in+ view(for: block)+ }+ }+ .frame(maxWidth: .infinity, alignment: .leading)+ }++ @ViewBuilder+ private func view(for block: MarkdownBlock) -> some View {+ switch block {+ case .heading(let level, let text):+ Text(text)+ .font(Self.headingFont(level: level))+ .foregroundStyle(AsterismColors.primaryText)+ .padding(.top, level == 1 ? 0 : 6)+ case .paragraph(let text):+ Text(Self.inline(text))+ .font(.body)+ .foregroundStyle(AsterismColors.primaryText)+ .fixedSize(horizontal: false, vertical: true)+ case .unorderedList(let items):+ list(items) { _ in "•" }+ case .orderedList(let items):+ // Numbered from 1 whatever the source wrote, which is the whole of+ // "ordered lists numbered from 1".+ list(items) { index in "\(index + 1)." }+ case .image(let alt, let asset):+ MarkdownImage(alt: alt, asset: asset)+ }+ }++ private func list(+ _ items: [String], marker: @escaping (Int) -> String+ ) -> some View {+ VStack(alignment: .leading, spacing: 6) {+ ForEach(Array(items.enumerated()), id: \.offset) { index, item in+ HStack(alignment: .firstTextBaseline, spacing: 8) {+ Text(marker(index))+ .font(.body)+ .foregroundStyle(AsterismColors.secondaryText)+ .accessibilityHidden(true)+ Text(Self.inline(item))+ .font(.body)+ .foregroundStyle(AsterismColors.primaryText)+ .fixedSize(horizontal: false, vertical: true)+ }+ }+ }+ }++ private static func headingFont(level: Int) -> Font {+ switch level {+ case 1: AsterismTypography.serifLargeTitle+ case 2: AsterismTypography.serifHeading+ default: AsterismTypography.serifRowTitle+ }+ }++ /// Bold, italic, code and links, which is all SwiftUI parses — and the+ /// plain string where the line will not parse, so a stray bracket costs the+ /// styling rather than the sentence.+ ///+ /// `.inlineOnlyPreservingWhitespace` because the block structure has already+ /// been decided: the full parser would swallow a leading `#` or `-` that+ /// reached this far as markup, and those are lines the subset deliberately+ /// carries through literally.+ static func inline(_ text: String) -> AttributedString {+ (try? AttributedString(+ markdown: text,+ options: AttributedString.MarkdownParsingOptions(+ interpretedSyntax: .inlineOnlyPreservingWhitespace)))+ ?? AttributedString(text)+ }+}++/// An image on a line of its own (Q15).+///+/// It **shrinks to the text column and never enlarges**: the frame caps the+/// picture at its own width, and `scaledToFit` keeps its aspect ratio inside+/// whatever width is left. A missing asset draws its alt text in its place —+/// the document reads correctly before the owner has added a screenshot, which+/// is what the drafts depend on.+private struct MarkdownImage: View {+ let alt: String+ let asset: String++ var body: some View {+ if let resolved = PlatformImages.named(asset) {+ resolved.image+ .resizable()+ .scaledToFit()+ .frame(maxWidth: resolved.pointSize.width)+ .clipShape(RoundedRectangle(cornerRadius: 8, style: .continuous))+ .accessibilityLabel(alt)+ } else {+ Text(alt)+ .font(.caption)+ .foregroundStyle(AsterismColors.secondaryText)+ }+ }+}++/// One bundled announcement, with the list of other bundled notes under it+/// (Q7).+///+/// The **sheet** wraps this in a `NavigationStack` with a Done button;+/// **Settings** pushes it bare. Which version is being shown is this view's own+/// state, so choosing another note replaces what is drawn without closing+/// anything (Decision 1).+struct AnnouncementDocumentView: View {+ /// What this build has bundled **and its text** (Q32), so both the document+ /// drawn and the list under it are lookups: nothing here opens a file.+ let catalog: AnnouncementCatalog++ /// Optional so a sheet presented for an announcement this build bundles+ /// nothing for still draws — and still carries its Done button. The arm+ /// below says what happened, in the one place that sentence lives.+ @State private var shown: AnnouncementDocument?++ init(document: AnnouncementDocument?, catalog: AnnouncementCatalog) {+ self.catalog = catalog+ _shown = State(initialValue: document)+ }++ /// The version now drawn, or nil where the document is not a release note.+ private var shownVersion: String? {+ if case .releaseNote(let version)? = shown { return version }+ return nil+ }++ /// Q7: every *other* bundled version, newest first. Empty for the+ /// getting-started guide, which is not one of a series.+ private var otherVersions: [String] {+ guard let shownVersion else { return [] }+ return catalog.otherReleaseNoteVersions(than: shownVersion)+ }++ var body: some View {+ ScrollView {+ VStack(alignment: .leading, spacing: 20) {+ if let shown, let text = catalog.text(for: shown) {+ MarkdownDocumentView(blocks: MarkdownBlocks.blocks(from: text))+ } else {+ // Reachable only where a row or a sheet was raised for a+ // document this catalog holds no text for; the rows+ // themselves are hidden when their document is missing.+ Text("This document could not be read.")+ .font(.body)+ .foregroundStyle(AsterismColors.secondaryText)+ }+ if !otherVersions.isEmpty { previousVersions }+ }+ .padding(.horizontal, 20)+ .padding(.vertical, 16)+ .frame(maxWidth: .infinity, alignment: .leading)+ }+ .scrollContentBackground(.hidden)+ .background(alignment: .topLeading) {+ Color.clear.uiTestMarker(LayoutMarker.announcementDocument)+ }+ }++ private var previousVersions: some View {+ VStack(alignment: .leading, spacing: 8) {+ ConstellationSectionHeader("Earlier versions", accent: .violet)+ ForEach(otherVersions, id: \.self) { version in+ AnnouncementCardButton(+ title: "Version \(version)",+ identifier: "announcement-version-\(version)",+ action: { shown = .releaseNote(version: version) })+ }+ }+ .padding(.top, 8)+ }+}++/// Every block kind at once, so the renderer can be read in both appearances+/// without a bundle behind it (task 4). The image line names an asset nothing+/// bundles, which is the missing-asset arm drawing its alt text.+private let previewDocument = """+ # Version 0.7.0++ Asterism now tells you what a release changed, and **how capturing works**+ if you have not started yet.++ ## What is new++ - A release note on Today+ - A getting-started guide+ - Both reachable from Settings++ ### How to read one++ 1. Open the Today tab+ 2. Tap the row above your notes+ 3. Tap Done when you have read it++ ++ | a | b |+ | - | - |+ """++#Preview("Document, light") {+ ScrollView {+ MarkdownDocumentView(blocks: MarkdownBlocks.blocks(from: previewDocument))+ .padding(20)+ }+ .background(AsterismColors.backgroundBottom)+ .preferredColorScheme(.light)+}++#Preview("Document, dark") {+ ScrollView {+ MarkdownDocumentView(blocks: MarkdownBlocks.blocks(from: previewDocument))+ .padding(20)+ }+ .background(AsterismColors.backgroundBottom)+ .preferredColorScheme(.dark)+}
diff --git a/Asterism/Asterism/AsterismApp.swift b/Asterism/Asterism/AsterismApp.swiftindex 20c898e7..f88c899a 100644--- a/Asterism/Asterism/AsterismApp.swift+++ b/Asterism/Asterism/AsterismApp.swift@@ -29,6 +29,16 @@ struct AsterismApp: App { /// Req 2.3 asks that the compact and wide trees be two views over one /// place, so the state has to outlive whichever of them is on screen. @State private var navigation = AppNavigation()+ /// The announcement seen state (`today-announcements` Q22), for both of the+ /// reasons above and one more: a `UserDefaults` write triggers no+ /// Observation, so the Mac's Settings window storing the version has to be+ /// storing it on the very object Today is watching.+ ///+ /// Built through `ContentView.launchSeenState()`, which applies the seeded+ /// launch's pin before constructing the state that reads it (Q14). The+ /// dependency is inside that function rather than in the order of these two+ /// declarations, so nothing here breaks if they are ever reordered.+ @State private var announcements = ContentView.launchSeenState() #if os(iOS) /// Watched only to know when the app has left the foreground, which is one@@ -67,7 +77,7 @@ struct AsterismApp: App { // New Window, and reopening the app brings that window forward rather // than opening another. Window("Asterism", id: Self.mainWindowID) {- ContentView(model: model, navigation: navigation)+ ContentView(model: model, navigation: navigation, announcements: announcements) // Req 2.4: the two-column layout with the list at 320 pt still // fits here. `contentMinSize` below is what makes the window // honour it rather than letting the reader squash the content.@@ -85,13 +95,17 @@ struct AsterismApp: App { SettingsScreen(model: model, navigation: navigation, dismissSheet: nil) } // Q18: this scene is built outside `ContentView`, so it inherits- // nothing from that write — the lookup is put in here too.+ // nothing from that write — the lookup is put in here too, and the+ // seen state with it (`today-announcements` Q22): it is the same+ // instance the main window holds, so Release notes opened here+ // removes the row over there. .environment(\.siteNames, model.siteNames)+ .environment(announcements) } .defaultSize(width: 640, height: 560) #else WindowGroup {- ContentView(model: model, navigation: navigation)+ ContentView(model: model, navigation: navigation, announcements: announcements) } // Req 6.1's shortcuts, which iPadOS also lists in the held-⌘ overlay. // Settings is the one command that is the iPad's alone (Q4): the Mac
diff --git a/Asterism/Asterism/ContentView.swift b/Asterism/Asterism/ContentView.swiftindex 5e09b6cf..9211d25d 100644--- a/Asterism/Asterism/ContentView.swift+++ b/Asterism/Asterism/ContentView.swift@@ -23,6 +23,12 @@ struct ContentView: View { /// the memory-pressure monitor) is this view's. @Bindable private var navigation: AppNavigation + /// `today-announcements` Q22: one instance, made beside the library model+ /// and handed to every scene, so a store made from the Mac's separate+ /// Settings window is observed by Today. A plain `let` for `navigation`'s+ /// reason — the object is the app's, and this view only reads it.+ private let announcements: AnnouncementSeenState+ /// When each half of an activation runs (Decision 5). Rate-limits the /// reconcile on the Mac, where activation fires on every application /// switch, and never on the phone, where it follows a suspension.@@ -95,17 +101,24 @@ struct ContentView: View { /// with something actually imported (Req 4.9). @State private var hasPrunedRestoredSelection = false - /// The scene's initializer: both objects are the app's, not this view's.- init(model: AppLibraryModel, navigation: AppNavigation) {+ /// The scene's initializer: all three objects are the app's, not this+ /// view's.+ init(+ model: AppLibraryModel,+ navigation: AppNavigation,+ announcements: AnnouncementSeenState+ ) { _model = State(initialValue: model) _navigation = Bindable(navigation)+ self.announcements = announcements } /// Test/Preview initializer — injects an explicit configuration and builds- /// navigation of its own, which the `Bindable` then retains.+ /// navigation and seen state of its own, which the properties then retain. init(configuration: LibraryConfiguration) { _model = State(initialValue: AppLibraryModel(configuration: configuration)) _navigation = Bindable(AppNavigation())+ announcements = AnnouncementSeenState() } /// The model this launch runs on.@@ -145,6 +158,33 @@ struct ContentView: View { #endif } + /// The announcement seen state this launch runs on (`today-announcements`+ /// Q14, Q22).+ ///+ /// **The pin is applied here, immediately before the state that reads it is+ /// constructed.** It used to sit in ``launchModel()``, which made the pin+ /// correct only for as long as `AsterismApp` happened to declare its model+ /// property above its announcements property — stored properties initialise+ /// in declaration order, so swapping two lines would have made the state+ /// read the *previous* launch's value, with nothing to fail the build.+ /// Applying it inside this function makes the order irrelevant: whenever the+ /// state is built, the key is already what this launch means it to be.+ ///+ /// On a seeded launch the key is *pinned* rather than reset — removed, it+ /// would put a release-note row on every fixture that holds entries (Q11)+ /// and shift the rows under the journeys. A journey that wants the row names+ /// an older version in `ASTERISM_UI_TEST_LAST_SEEN_VERSION`.+ static func launchSeenState() -> AnnouncementSeenState {+ #if DEBUG || ASTERISM_PERFORMANCE_TESTING+ if case .seeded = UITestLaunchSupport.request() {+ UITestLaunchSupport.pinLastSeenVersion(+ in: .standard,+ currentVersion: AnnouncementSeenState.marketingVersion())+ }+ #endif+ return AnnouncementSeenState()+ }+ /// The model the app runs on, built from what this build's bundle declares. /// /// The two parameters are the seam a test reaches this through, and both@@ -339,10 +379,34 @@ struct ContentView: View { guard RuntimePlatform.isMac else { return } storedWorkID = workID?.uuidString ?? "" }+ // Two things the published snapshot settles, in one handler because+ // they read one value and neither depends on the other.+ // // Req 4.9: a restored id is kept until the library has imported at // least once, and only then held to what actually resolves.- .onChange(of: model.snapshotGeneration) { _, _ in+ //+ // `today-announcements` Q11's silent store, keyed by the snapshot+ // generation: a device that has read an empty library takes the current+ // version without showing a note, so a device joining an existing+ // library never announces the version that was current when it joined.+ //+ // **Here, not on Today** (Q22). The Mac restores its last tab, so the+ // Today screen may not be mounted when the library is first read — and+ // this store has no undo. Not in a `body` either: it writes.+ //+ // `initial: true` because the generation is the *only* key: a first+ // publication that landed before this modifier installed would leave the+ // store unrun for the whole launch, and a launch that never runs it is a+ // launch that may announce a version the device only just joined. Both+ // calls are idempotent — the store guards on nothing being stored yet,+ // and the prune keeps every restored id until the library has imported+ // once — so running them at install costs an evaluation and nothing else.+ .onChange(of: model.snapshotGeneration, initial: true) { _, generation in pruneRestoredSelection()+ announcements.storeVersionSilentlyIfNeeded(+ libraryHasBeenRead: ArrivingLibraryPresentation.hasContent(+ snapshotGeneration: generation),+ libraryHasNoEntries: model.todayPresentation.groups.isEmpty) } // `update-schedule` Req 3.7: the current day moved, so a selection that // *was* the current day moves with it.@@ -515,6 +579,13 @@ struct ContentView: View { // reaches both trees, everything they push and every sheet, and no // row signature changes to carry it. .environment(\.thumbnailLoader, model.thumbnailLoader)+ // `today-announcements` Q22: the seen state, written beside those+ // two and for the same reason. Today reads it to decide its row and+ // Settings reads it to store on open; both are reached from here,+ // and neither signature changes to carry it. The Mac's Settings+ // window is a second scene and gets its own write in `AsterismApp`,+ // of the same instance.+ .environment(announcements) } private var presentedContent: some View {@@ -603,6 +674,33 @@ struct ContentView: View { ComposedTeachingContainerView(model: teachModel) } }+ // `today-announcements` Q4, Q23: the announcement's document, with+ // a Done button. `item:` like the two sheets above, keyed by the+ // announcement rather than by the version shown inside it.+ //+ // **The store happens on the way out, not on the way in** (Q4):+ // hiding the row when the sheet opens would make an accidental tap+ // permanent before anything was read. It is written from the+ // `onChange` below rather than from `onDismiss`, which cannot say+ // *which* item was dismissed — by the time it runs the binding is+ // already nil, and only a release note stores anything (Q17's+ // Settings route stores its own).+ //+ // The document is looked up here and passed **optional**: a sheet+ // whose body drew nothing would present an empty sheet with no Done+ // button, which on the Mac has no dismiss gesture either. The sheet+ // itself says what happened instead.+ .sheet(item: $navigation.presentedAnnouncement) { announcement in+ AnnouncementSheet(+ announcement: announcement,+ document: announcements.document(for: announcement),+ catalog: announcements.catalog,+ onDone: { navigation.presentedAnnouncement = nil })+ }+ .onChange(of: navigation.presentedAnnouncement) { previous, current in+ guard current == nil, case .releaseNote? = previous else { return }+ announcements.recordReleaseNoteSeen()+ } // The diagnosis and Sites screens' re-teach route (Reqs 4.5, 6.2). // Keyed by hostname rather than Entry: a diagnosed Site's rows carry // no action, so there is no pill to enter it from.
diff --git a/Asterism/Asterism/Layout/AppNavigation.swift b/Asterism/Asterism/Layout/AppNavigation.swiftindex ca45087e..54a72ff4 100644--- a/Asterism/Asterism/Layout/AppNavigation.swift+++ b/Asterism/Asterism/Layout/AppNavigation.swift@@ -300,6 +300,17 @@ final class AppNavigation { /// own state, because that stack is not the Works tab's. var mergeSheetEntryID: UUID? + /// The announcement whose document is on screen (`today-announcements`+ /// Q22).+ ///+ /// Here rather than on the Today screen for the reason every other sheet is+ /// here: two presentations in one turn drop the second, so every sheet in+ /// this window goes through one place. Keyed by the announcement and+ /// **never by the version shown inside it** — the document view moves+ /// between bundled versions as its own state, and a key carrying the+ /// version would tear the sheet down on every such move.+ var presentedAnnouncement: TodayAnnouncement?+ // MARK: - The route waiting for Settings to close /// The route a Settings-hosted surface asked for, taken once Settings has
diff --git a/Asterism/Asterism/Layout/AppScreens.swift b/Asterism/Asterism/Layout/AppScreens.swiftindex 8c2c666d..28aeb8cd 100644--- a/Asterism/Asterism/Layout/AppScreens.swift+++ b/Asterism/Asterism/Layout/AppScreens.swift@@ -84,6 +84,15 @@ struct AppScreens { // lists' fields and the keyboard came up unasked on the next switch. searchFocusRequest: navigation.searchFocusRequest(for: .today), showsSky: showsSky,+ // `today-announcements` Q21: a published snapshot, which is the+ // distinction `ArrivingLibraryPresentation` already draws for+ // Stats — the model reaches `.ready` even when its first refresh+ // failed, leaving the initial empty presentation in place.+ libraryHasBeenRead: ArrivingLibraryPresentation.hasContent(+ snapshotGeneration: model.snapshotGeneration),+ // Q22: the sheet is `ContentView`'s, like every other sheet in this+ // window.+ onOpenAnnouncement: { navigation.presentedAnnouncement = $0 }, // A noted row clears the Today stack under it, so the entry is the // pane's whole content — the Works list's unattached route's shape. onSelect: navigation.showTodayEntry,
diff --git a/Asterism/Asterism/Support/PlatformModifiers.swift b/Asterism/Asterism/Support/PlatformModifiers.swiftindex cda96cd6..46641539 100644--- a/Asterism/Asterism/Support/PlatformModifiers.swift+++ b/Asterism/Asterism/Support/PlatformModifiers.swift@@ -205,6 +205,64 @@ extension View { } } +// MARK: - Images by name (`today-announcements` Q15, Q27)++/// An image the platform resolved, and the size it reports for it.+///+/// The size is what lets a bundled document's picture **shrink to the text+/// column and never enlarge**: SwiftUI's `Image(_:)` reports neither absence nor+/// dimensions, so the lookup goes through the platform's image type and hands+/// both back.+struct PlatformNamedImage {+ let image: Image+ /// The image's own size, in points.+ let pointSize: CGSize+}++/// The two named-image lookups, at the seam rather than in a view (Req 4.5).+///+/// Neither arm imports UIKit or AppKit: `import SwiftUI` re-exports the+/// platform's own framework, which is how `RuntimePlatform.isPhone` reaches+/// `UIDevice` above.+enum PlatformImages {+ /// An asset-catalog image by name, or nil when the asset is absent — which+ /// is what a document's alt text stands in for (Q15).+ static func named(_ name: String) -> PlatformNamedImage? {+ #if os(macOS)+ guard let image = NSImage(named: name) else { return nil }+ return PlatformNamedImage(image: Image(nsImage: image), pointSize: image.size)+ #else+ guard let image = UIImage(named: name) else { return nil }+ return PlatformNamedImage(image: Image(uiImage: image), pointSize: image.size)+ #endif+ }++ /// This build's own app icon, for the announcement row's cover slot.+ ///+ /// **Keyed on what the bundle declares, never on a bundle identifier**+ /// (Q27): `make verify-identity` rejects an identifier literal in Swift, and+ /// `Development` and `Personal` declare different icon names — so each shows+ /// its own icon without this knowing either name. On iOS the primary icon's+ /// last file is the largest; on the Mac the running application has its icon+ /// directly.+ @MainActor+ static func appIcon(in bundle: Bundle = .main) -> PlatformNamedImage? {+ #if os(macOS)+ let icon = NSApplication.shared.applicationIconImage+ guard let icon else { return nil }+ return PlatformNamedImage(image: Image(nsImage: icon), pointSize: icon.size)+ #else+ guard+ let icons = bundle.object(forInfoDictionaryKey: "CFBundleIcons") as? [String: Any],+ let primary = icons["CFBundlePrimaryIcon"] as? [String: Any],+ let files = primary["CFBundleIconFiles"] as? [String],+ let name = files.last+ else { return nil }+ return named(name)+ #endif+ }+}+ // MARK: - The window's sky (Req 3.1) extension View {
diff --git a/Asterism/Asterism/Support/UITestMarker.swift b/Asterism/Asterism/Support/UITestMarker.swiftindex f615eb5a..220d9ca0 100644--- a/Asterism/Asterism/Support/UITestMarker.swift+++ b/Asterism/Asterism/Support/UITestMarker.swift@@ -56,6 +56,12 @@ enum LayoutMarker { /// three states are a single sentence and a container's identifier is /// inherited by the one element inside it. static let coverCandidateSheet = "cover-candidate-sheet"+ /// A rendered announcement document (`today-announcements`), in the sheet+ /// and in Settings alike. A marker layer rather than an identifier on the+ /// scroll view, for `coverCandidateSheet`'s reason: a container's identifier+ /// is inherited by everything inside it, and the versions list under a+ /// release note holds buttons of its own.+ static let announcementDocument = "announcement-document" } /// The `@AppStorage` keys the Mac's relaunch restore reads and writes (Req 7.2,
diff --git a/Asterism/Asterism/UITestLaunchSupport.swift b/Asterism/Asterism/UITestLaunchSupport.swiftindex 34cb422c..227e3341 100644--- a/Asterism/Asterism/UITestLaunchSupport.swift+++ b/Asterism/Asterism/UITestLaunchSupport.swift@@ -134,6 +134,10 @@ enum UITestLaunchRequest: Equatable { enum UITestLaunchSupport { static let scenarioKey = "ASTERISM_UI_TEST_SCENARIO" static let runIDKey = "ASTERISM_UI_TEST_RUN_ID"+ /// `today-announcements` Q14: which last-seen version this launch starts+ /// from. Absent means the version now running, so no fixture shows a+ /// release-note row.+ static let lastSeenVersionKey = "ASTERISM_UI_TEST_LAST_SEEN_VERSION" static let seededScenario = "seeded-m1" static let seededTaughtScenario = "seeded-taught" static let seededScaleM4Scenario = "seeded-scale-m4"@@ -452,4 +456,32 @@ enum UITestLaunchSupport { fixture: fixture ) }++ /// What a seeded launch starts with in `announcements.lastSeenVersion`+ /// (`today-announcements` Q14).+ ///+ /// **Pinned rather than removed**, unlike the Works list's sort: with the+ /// key absent, Q11 would put a release-note row on every fixture that holds+ /// entries and shift the rows under a large number of existing journeys. The+ /// version now running is therefore the default, and a journey that wants+ /// the row names an older one in `ASTERISM_UI_TEST_LAST_SEEN_VERSION`.+ ///+ /// Written before the seen state is created, so nothing reads the key first.+ static func pinnedLastSeenVersion(+ currentVersion: String,+ environmentProvider: any ProcessEnvironmentProviding = SystemProcessEnvironment()+ ) -> String {+ environmentProvider.environment[lastSeenVersionKey] ?? currentVersion+ }++ static func pinLastSeenVersion(+ in defaults: UserDefaults,+ currentVersion: String,+ environmentProvider: any ProcessEnvironmentProviding = SystemProcessEnvironment()+ ) {+ defaults.set(+ pinnedLastSeenVersion(+ currentVersion: currentVersion, environmentProvider: environmentProvider),+ forKey: AnnouncementSeenState.lastSeenVersionKey)+ } }
diff --git a/Asterism/Asterism/ViewModels/AnnouncementSeenState.swift b/Asterism/Asterism/ViewModels/AnnouncementSeenState.swiftnew file mode 100644index 00000000..f4b319cd--- /dev/null+++ b/Asterism/Asterism/ViewModels/AnnouncementSeenState.swift@@ -0,0 +1,159 @@+import Foundation++/// The last release note this device has seen, and what this build has bundled+/// (`today-announcements` Decision 2).+///+/// **Per device, and it does not sync** (Q8): each device decides for itself,+/// and syncing a flag would need a schema bump for a value whose loss costs one+/// extra row. `UserDefaults` rather than a marker file, over an **injected**+/// store so a test can hand it a throwaway suite — none of the four reasons the+/// project's marker files exist applies here (Decision 2): only the app reads+/// it, nothing depends on it before a store opens, a lost write is harmless, and+/// it describes the install rather than the library.+///+/// One instance is made beside `AppLibraryModel` and handed to every scene+/// (Q22), so a store made from the Mac's separate Settings window is observed by+/// Today — a `UserDefaults` write triggers no Observation of its own.+@Observable+final class AnnouncementSeenState {+ /// Q12: one key. Prism's `hasLaunchedBefore` is deliberately not ported —+ /// library emptiness is this feature's first-launch signal (Q5, Q11).+ static let lastSeenVersionKey = "announcements.lastSeenVersion"++ @ObservationIgnored private let defaults: UserDefaults++ /// The stored value, or nil when none has been stored. A stored property so+ /// Observation republishes the row when it moves.+ private(set) var lastSeenVersion: String?++ /// `CFBundleShortVersionString`, read once.+ let currentVersion: String++ /// What this build has bundled **and can read, with its text**, taken once+ /// at creation: the documents cannot change while the app is running, and a+ /// document that is present but empty is not one (Q29, closed in task 8).+ ///+ /// Reading them here is what lets every gate below be a pure lookup, and+ /// what lets the document view draw without reopening a file. A disk read+ /// inside `document(for:)` would sit on Today's hot path, since the row asks+ /// on every `body` evaluation.+ let catalog: AnnouncementCatalog++ init(defaults: UserDefaults = .standard, bundle: Bundle = .main) {+ self.defaults = defaults+ lastSeenVersion = defaults.string(forKey: Self.lastSeenVersionKey)+ currentVersion = Self.marketingVersion(in: bundle)+ catalog = BundledAnnouncements.catalog(in: bundle)+ }++ /// The marketing version this build declares, or an empty string where the+ /// bundle declares none — which is a bundle no note is ever bundled for, so+ /// it announces nothing.+ static func marketingVersion(in bundle: Bundle = .main) -> String {+ bundle.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? ""+ }++ /// The document behind an announcement, or nil where this build bundles+ /// none for it.+ ///+ /// The Mac's getting-started variant is chosen here (Q16), which is why the+ /// platform arrives as a parameter rather than being read inside.+ func document(+ for announcement: TodayAnnouncement,+ isMac: Bool = RuntimePlatform.isMac+ ) -> AnnouncementDocument? {+ switch announcement {+ case .gettingStarted:+ return catalog.gettingStartedDocument(isMac: isMac)+ case .releaseNote(let version):+ guard catalog.releaseNoteVersions.contains(version) else { return nil }+ return .releaseNote(version: version)+ }+ }++ /// The announcement Today should draw, or nil for none — the task 1 rule+ /// asked with this device's stored value and this build's documents.+ ///+ /// **An announcement with no document is not drawn.** The rule itself knows+ /// about bundled release notes (Q9); this is the same bar applied to the+ /// guide, and the same bar Settings applies to its rows: a row that opened+ /// on "this document could not be read" would be a row that should not have+ /// been there. Since task 8 that is literally one bar — the catalog holds+ /// only documents whose text read at construction (Q29).+ ///+ /// **Today's settled empty-library message keys off this same answer**, not+ /// off the branch: a build bundling no guide draws no row, and must keep the+ /// message it would otherwise have replaced.+ func announcement(+ libraryHasBeenRead: Bool,+ libraryHasNoEntries: Bool,+ isAwaitingFirstSync: Bool,+ selectedDayHasNotedSection: Bool,+ showsSingleCurrentDay: Bool+ ) -> TodayAnnouncement? {+ guard+ let row = TodayAnnouncements.row(+ libraryHasBeenRead: libraryHasBeenRead,+ libraryHasNoEntries: libraryHasNoEntries,+ isAwaitingFirstSync: isAwaitingFirstSync,+ selectedDayHasNotedSection: selectedDayHasNotedSection,+ showsSingleCurrentDay: showsSingleCurrentDay,+ lastSeenVersion: lastSeenVersion,+ currentVersion: currentVersion,+ bundledVersions: catalog.releaseNoteVersions),+ document(for: row) != nil+ else { return nil }+ return row+ }++ /// What Settings' **Release notes** row opens: the newest bundled note+ /// (Q7, Q17), or nil when there is none to open.+ ///+ /// The requirement hides the row when its document is missing, **unreadable+ /// or empty** — three states a directory listing cannot tell apart, which is+ /// why the catalog is built from documents that read rather than from names+ /// (Q29). Settings and Today now consult one answer instead of two.+ var settingsReleaseNoteDocument: AnnouncementDocument? {+ catalog.newestReleaseNoteVersion.map { .releaseNote(version: $0) }+ }++ /// What Settings' **Getting started** row opens, or nil where this build+ /// bundles no guide it can read — the same bar, and on the Mac the same+ /// variant Today would show (Q16).+ var settingsGettingStartedDocument: AnnouncementDocument? {+ document(for: .gettingStarted)+ }++ /// Records the current version as seen, which removes the row (Q4).+ ///+ /// Called when a release-note sheet closes and when Release notes is opened+ /// from Settings (Q17). Closing the getting-started sheet stores nothing —+ /// there is no version it could be about.+ func recordReleaseNoteSeen() {+ store(currentVersion)+ }++ /// Q11's silent store: a read library with no entries and nothing stored+ /// takes the current version without showing a note, arriving or settled.+ ///+ /// - Returns: whether anything was stored, so a caller can say so in a test.+ @discardableResult+ func storeVersionSilentlyIfNeeded(+ libraryHasBeenRead: Bool,+ libraryHasNoEntries: Bool+ ) -> Bool {+ guard+ TodayAnnouncements.storesVersionSilently(+ libraryHasBeenRead: libraryHasBeenRead,+ libraryHasNoEntries: libraryHasNoEntries,+ lastSeenVersion: lastSeenVersion)+ else { return false }+ store(currentVersion)+ return true+ }++ private func store(_ version: String) {+ defaults.set(version, forKey: Self.lastSeenVersionKey)+ lastSeenVersion = version+ }+}
diff --git a/Asterism/Asterism/ViewModels/TodayAnnouncements.swift b/Asterism/Asterism/ViewModels/TodayAnnouncements.swiftnew file mode 100644index 00000000..8a66d94c--- /dev/null+++ b/Asterism/Asterism/ViewModels/TodayAnnouncements.swift@@ -0,0 +1,198 @@+import Foundation++/// The one announcement Today may show above its content sections+/// (`today-announcements`).+///+/// It is **not an entry** (Q1): it carries no Teach or Resolve action, never+/// enters search, the day plan or the duplicate plan, and is identified by what+/// it is rather than by any record. The row copies the entry row's look and+/// nothing else.+nonisolated enum TodayAnnouncement: Equatable, Hashable, Identifiable {+ /// The guide a reader with nothing captured is shown, in place of the+ /// settled empty-library message (Q5).+ case gettingStarted+ /// The note for the version now running, until the reader has closed it+ /// (Q4).+ case releaseNote(version: String)++ /// Q3: exactly these words, and nothing else on the row.+ var title: String {+ switch self {+ case .gettingStarted: "Getting started"+ case .releaseNote(let version): "Version \(version)"+ }+ }++ /// The title over this announcement's document, which is the **kind** of+ /// document rather than the row's `Version <number>` (Q34).+ ///+ /// Delegated to ``AnnouncementDocument/documentTitle`` so the sheet and+ /// Settings name one document identically without either view owning the+ /// string.+ var documentTitle: String {+ switch self {+ case .gettingStarted: AnnouncementDocument.gettingStarted.documentTitle+ case .releaseNote(let version):+ AnnouncementDocument.releaseNote(version: version).documentTitle+ }+ }++ /// **Not the version** (Q22): the sheet is keyed by this, and the document+ /// view lets the reader move between bundled versions as its own state. An+ /// id carrying the version would tear the sheet down and rebuild it on every+ /// such move.+ var id: String {+ switch self {+ case .gettingStarted: "getting-started"+ case .releaseNote: "release-note"+ }+ }++ /// The row's accessibility identifier, which is also what the UI journeys+ /// address it by.+ var identifier: String {+ switch self {+ case .gettingStarted: "today-announcement-getting-started"+ case .releaseNote: "today-announcement-release-note"+ }+ }+}++/// Which announcement Today shows, when the current version is stored without+/// showing one, and how two version strings order.+///+/// Pure rules in the shape of `ArrivingLibraryPresentation` (Q13): a+/// `nonisolated enum` of static functions in the app target, so `make+/// test-quick` covers them and the share extension — which has no use for any of+/// this — is untouched.+nonisolated enum TodayAnnouncements {+ // MARK: - Which row shows++ /// The announcement to draw, or nil for none.+ ///+ /// - Parameters:+ /// - libraryHasBeenRead: a snapshot has been published (Q21). Before that+ /// an empty Today proves nothing: `AppLibraryModel` reaches `.ready`+ /// even when its first refresh failed, with the initial empty+ /// presentation still in place — and a full library showing Getting+ /// started would also store the version, which has no undo.+ /// - libraryHasNoEntries: the empty-library branch, which is the test the+ /// settled message uses. A library with works and no entries counts as+ /// empty (Q28).+ /// - isAwaitingFirstSync: nothing has reached this device from iCloud yet.+ /// Getting started never shows while a library is arriving (Q5).+ /// - selectedDayHasNotedSection: the day on screen draws a noted section —+ /// today or a past day, never a future one.+ /// - showsSingleCurrentDay: Today is showing the current day as one day,+ /// with no search query and no banner filter (Q2). The release note's+ /// condition only; Getting started ignores the query (Q20).+ /// - lastSeenVersion: the stored per-device value, or nil when none is+ /// stored.+ /// - currentVersion: `CFBundleShortVersionString`.+ /// - bundledVersions: the versions a note is bundled for. A version+ /// without one announces nothing (Q9).+ static func row(+ libraryHasBeenRead: Bool,+ libraryHasNoEntries: Bool,+ isAwaitingFirstSync: Bool,+ selectedDayHasNotedSection: Bool,+ showsSingleCurrentDay: Bool,+ lastSeenVersion: String?,+ currentVersion: String,+ bundledVersions: [String]+ ) -> TodayAnnouncement? {+ guard libraryHasBeenRead else { return nil }++ // Q6: at most one row, and this one wins. A reader with nothing+ // captured needs the guide more than the note.+ if libraryHasNoEntries {+ guard !isAwaitingFirstSync, selectedDayHasNotedSection else { return nil }+ return .gettingStarted+ }++ guard showsSingleCurrentDay else { return nil }+ guard bundledVersions.contains(currentVersion) else { return nil }+ // Q10: string inequality, so a downgrade counts as a change.+ guard lastSeenVersion != currentVersion else { return nil }+ return .releaseNote(version: currentVersion)+ }++ // MARK: - The message the row replaces (Q5, Q20, Q29)++ /// Whether Today still draws its settled empty-library message.+ ///+ /// **The coupling this exists to pin**: the message stands down for a+ /// getting-started row that is *actually drawn*, never for the branch alone.+ /// A build that bundles no guide, or whose guide will not read, draws no row+ /// (Q29) — and a condition written as `branch != .emptyLibrary` would leave+ /// such a library showing neither the row nor the message it replaces, which+ /// is the blank screen phase 1's review warned about. That rewrite passes+ /// every test in the repo unless the rule lives somewhere a test can reach+ /// it, which is why it is here rather than inline in a `body`.+ ///+ /// - Parameters:+ /// - branch: the display branch. Only `.emptyLibrary` has a message at all.+ /// - announcement: what the row will actually draw, `nil` for none — the+ /// gated answer from ``AnnouncementSeenState/announcement(libraryHasBeenRead:libraryHasNoEntries:isAwaitingFirstSync:selectedDayHasNotedSection:showsSingleCurrentDay:)``,+ /// not the ungated one from ``row(libraryHasBeenRead:libraryHasNoEntries:isAwaitingFirstSync:selectedDayHasNotedSection:showsSingleCurrentDay:lastSeenVersion:currentVersion:bundledVersions:)``.+ static func drawsEmptyLibraryMessage(+ branch: TodayDisplayPlan.Branch,+ announcement: TodayAnnouncement?+ ) -> Bool {+ branch == .emptyLibrary && announcement != .gettingStarted+ }++ // MARK: - The silent store++ /// Whether to store the current version without showing anything (Q11).+ ///+ /// A read library with no entries and nothing stored is a device that has+ /// never held this reader's library: a fresh install, or one joining an+ /// existing library from iCloud. Either way the note that was current when+ /// it joined is not news. Arriving or settled, and whichever screen is+ /// showing — which is why `ContentView` runs it rather than Today (Q22).+ static func storesVersionSilently(+ libraryHasBeenRead: Bool,+ libraryHasNoEntries: Bool,+ lastSeenVersion: String?+ ) -> Bool {+ libraryHasBeenRead && libraryHasNoEntries && lastSeenVersion == nil+ }++ // MARK: - Version ordering (Q10, Q26)++ /// Whether `version` is a dotted run of integers, which is the only shape a+ /// note file's version may take (Q26). Anything else — `1.1-beta`, `latest`,+ /// an empty string — is ignored rather than read with its suffix dropped,+ /// which would collide `1.1-beta` with `1.1`.+ static func isDottedIntegers(_ version: String) -> Bool {+ let components = version.split(separator: ".", omittingEmptySubsequences: false)+ guard !components.isEmpty else { return false }+ return components.allSatisfy { component in+ !component.isEmpty && component.allSatisfy { $0.isASCII && $0.isNumber }+ }+ }++ /// Numeric comparison per dotted component, with a missing component read as+ /// zero — so `0.10.0` is newer than `0.9`, where a string comparison would+ /// say the opposite.+ static func isVersion(_ lhs: String, newerThan rhs: String) -> Bool {+ let left = components(of: lhs)+ let right = components(of: rhs)+ for index in 0..<max(left.count, right.count) {+ let lhsValue = index < left.count ? left[index] : 0+ let rhsValue = index < right.count ? right[index] : 0+ if lhsValue != rhsValue { return lhsValue > rhsValue }+ }+ return false+ }++ /// The bundled versions newest first, for the list under a release note.+ static func sortedNewestFirst(_ versions: [String]) -> [String] {+ versions.sorted { isVersion($0, newerThan: $1) }+ }++ private static func components(of version: String) -> [Int] {+ version.split(separator: ".").map { Int($0) ?? 0 }+ }+}
diff --git a/Asterism/Asterism/Views/AnnouncementSheet.swift b/Asterism/Asterism/Views/AnnouncementSheet.swiftnew file mode 100644index 00000000..c0d043d1--- /dev/null+++ b/Asterism/Asterism/Views/AnnouncementSheet.swift@@ -0,0 +1,48 @@+import ConstellationKit+import SwiftUI++/// The sheet an announcement row opens (`today-announcements` Q23).+///+/// A stack of its own with a **Done** button, because a Mac sheet has no+/// dismiss gesture — and because the reader has to be able to leave a document+/// they opened by accident. It is presented from `ContentView` through+/// `AppNavigation`, so it **stays open when its row disappears underneath it**:+/// a first capture arriving while Getting started is up must not tear it down,+/// and neither must the release-note row going when the version is stored.+///+/// Settings pushes ``AnnouncementDocumentView`` bare instead — same document,+/// same versions list, no sheet chrome.+struct AnnouncementSheet: View {+ let announcement: TodayAnnouncement+ /// Optional deliberately: a sheet raised for an announcement this build+ /// bundles nothing for presents with its Done button and the document+ /// view's "could not be read" arm, rather than as an empty sheet a Mac+ /// reader cannot dismiss.+ let document: AnnouncementDocument?+ /// What this build has bundled, with the text of each document — the one+ /// answer both the drawn document and the versions list come from, so the+ /// two cannot disagree about which bundle they read (Q32).+ let catalog: AnnouncementCatalog+ let onDone: () -> Void++ var body: some View {+ NavigationStack {+ AnnouncementDocumentView(document: document, catalog: catalog)+ // The **kind** of document, not the version inside it (Q34),+ // and the same title Settings' route gives it — it is the+ // document's own, so neither view owns the other's string.+ .navigationTitle(announcement.documentTitle)+ .inlineNavigationTitle()+ .toolbar {+ ToolbarItem(placement: .confirmationAction) {+ Button("Done", action: onDone)+ .frame(+ minWidth: AsterismLayout.minHitTarget,+ minHeight: AsterismLayout.minHitTarget+ )+ .accessibilityIdentifier("announcement-done")+ }+ }+ }+ }+}
diff --git a/Asterism/Asterism/Views/SettingsView.swift b/Asterism/Asterism/Views/SettingsView.swiftindex 38257daf..62569b85 100644--- a/Asterism/Asterism/Views/SettingsView.swift+++ b/Asterism/Asterism/Views/SettingsView.swift@@ -18,6 +18,11 @@ struct SettingsView: View { /// lazy list row (the `WorkDetailView` rule). @State private var showingArrivingImportConfirmation = false + /// `today-announcements` Q22: the one seen state, written at the top of+ /// both scenes. Optional so a preview that does not write it simply shows+ /// no About section.+ @Environment(AnnouncementSeenState.self) private var announcements: AnnouncementSeenState?+ /// Req 4.2's second route to the diagnosis screen. The screen reads the /// diagnoses in its own `task`, so holding the model from here does not pin /// it to the moment Settings opened.@@ -160,6 +165,8 @@ struct SettingsView: View { creatorRolesSection + aboutSection+ Section { interruptedImportRow backupRow@@ -255,6 +262,66 @@ struct SettingsView: View { } } + // MARK: - About (`today-announcements` Q17)++ /// Directly above Backup: the bundled documents are reader-facing reading+ /// matter, not a diagnostic, and Settings had no About section at all.+ ///+ /// Each row is **hidden when its document is missing, unreadable or empty**,+ /// which is why the state's catalog holds only documents whose text read+ /// (Q29); where neither reads, the section itself is not drawn.+ /// Opening Release notes stores the current version as last seen (Q17) —+ /// including on the Mac, where Settings is a window of its own and the+ /// Today row is in+ /// another one: the seen state is one object written into both scenes+ /// (Q22), so the store there removes the row here.+ @ViewBuilder+ private var aboutSection: some View {+ if let announcements,+ announcements.settingsGettingStartedDocument != nil+ || announcements.settingsReleaseNoteDocument != nil {+ Section {+ // Getting started first: it is the one a reader who came looking+ // for help is after, and the one Today gives precedence to (Q6).+ if let guide = announcements.settingsGettingStartedDocument {+ NavigationLink {+ document(guide, in: announcements)+ .navigationTitle(guide.documentTitle)+ .inlineNavigationTitle()+ } label: {+ Label(guide.documentTitle, systemImage: "book")+ }+ .accessibilityIdentifier("settings-getting-started")+ }+ if let note = announcements.settingsReleaseNoteDocument {+ NavigationLink {+ document(note, in: announcements)+ .navigationTitle(note.documentTitle)+ .inlineNavigationTitle()+ // On the destination rather than on the row: a row+ // that stored on *tap* would store when a swipe-back+ // cancelled the push. Nothing equivalent hangs off+ // the guide — closing it stores nothing (Q5).+ .onAppear { announcements.recordReleaseNoteSeen() }+ } label: {+ Label(note.documentTitle, systemImage: "sparkles")+ }+ .accessibilityIdentifier("settings-release-notes")+ }+ } header: {+ ConstellationSectionHeader("About", accent: .violet)+ }+ }+ }++ /// Both rows push the bare document view, which draws the text the catalog+ /// read when it was built (Q32) — no second read, and no bundle to carry.+ private func document(+ _ document: AnnouncementDocument, in announcements: AnnouncementSeenState+ ) -> some View {+ AnnouncementDocumentView(document: document, catalog: announcements.catalog)+ }+ // MARK: - Debug Section (T-2117) /// The diagnostic surfaces — sync status and Check Library — behind one
diff --git a/Asterism/Asterism/Views/TodayAnnouncementRow.swift b/Asterism/Asterism/Views/TodayAnnouncementRow.swiftnew file mode 100644index 00000000..a000292c--- /dev/null+++ b/Asterism/Asterism/Views/TodayAnnouncementRow.swift@@ -0,0 +1,83 @@+import AsterismCore+import ConstellationKit+import SwiftUI++/// Today's announcement row (`today-announcements` Q1, Q3).+///+/// **It looks like an entry row and is not one.** The card, the padding, the+/// minimum height, the title face and the cover-slot geometry are+/// `TodayEntryRow`'s, copied rather than shared: this row takes no+/// `TodayPresentationRow`, carries no Teach or Resolve pill, takes no selection+/// highlight and never enters search, the day plan, the duplicate plan or any+/// count. The two layouts are separate code, so a later change to the entry+/// card has to be made in both — which is the price of the row not being an+/// entry (Q1).+///+/// One line of text and the app icon, and nothing else. The icon is this+/// build's own — `Development` and `Personal` each show theirs — and it is+/// hidden from accessibility, because the title is the whole of what the row+/// says.+///+/// The card itself is ``AnnouncementCardButton``, shared with the+/// previous-versions list under a release note. What is copied from+/// `TodayEntryRow` and must be kept in step with it is the *slot geometry*+/// below; the button around it is this feature's own.+struct TodayAnnouncementRow: View {+ let announcement: TodayAnnouncement+ let onOpen: (TodayAnnouncement) -> Void++ /// Req 6.2's linear scaling with the body text size, capped — the probe+ /// `ThumbnailSlot` uses, through the same geometry, so the icon slot and a+ /// cover slot are the same box at every text size.+ @ScaledMetric(relativeTo: .body) private var typeSizeProbe: CGFloat = 100+ @Environment(\.displayScale) private var displayScale++ private var slotSize: CGSize {+ CoverSlotGeometry(+ shape: .portrait,+ baseSize: AsterismLayout.coverSize,+ typeSizeProbe: typeSizeProbe,+ displayScale: displayScale+ ).drawnSize+ }++ var body: some View {+ AnnouncementCardButton(+ title: announcement.title,+ identifier: announcement.identifier,+ action: { onOpen(announcement) }+ ) {+ iconSlot+ }+ }++ /// The cover slot's box with the icon fitted and centred in it. The slot+ /// keeps its width when the icon will not load, so the row's text sits+ /// where it sits on every other row.+ private var iconSlot: some View {+ Group {+ if let icon = PlatformImages.appIcon() {+ icon.image+ .resizable()+ .scaledToFit()+ .clipShape(+ RoundedRectangle(+ cornerRadius: AsterismLayout.coverSlotRadius, style: .continuous))+ } else {+ Color.clear+ }+ }+ .frame(width: slotSize.width, height: slotSize.height)+ .padding(.trailing, 10)+ .accessibilityHidden(true)+ }+}++#Preview("Announcement rows") {+ VStack(spacing: 8) {+ TodayAnnouncementRow(announcement: .releaseNote(version: "0.7.0"), onOpen: { _ in })+ TodayAnnouncementRow(announcement: .gettingStarted, onOpen: { _ in })+ }+ .padding()+ .background(AsterismColors.backgroundBottom)+}
diff --git a/Asterism/Asterism/Views/TodayView.swift b/Asterism/Asterism/Views/TodayView.swiftindex 074d9baa..f0222e9f 100644--- a/Asterism/Asterism/Views/TodayView.swift+++ b/Asterism/Asterism/Views/TodayView.swift@@ -102,11 +102,23 @@ struct TodayView: View { /// Req 3.1: false in the wide tree, where the window paints one sky behind /// every column and a second layer here would be a column painting its own. let showsSky: Bool+ /// `today-announcements` Q21: whether a snapshot of the library has been+ /// published. An empty screen before that proves nothing — the model+ /// reaches `.ready` even when its first refresh failed — and no+ /// announcement may be drawn on it.+ let libraryHasBeenRead: Bool+ /// The announcement row's tap: the sheet is `ContentView`'s, through+ /// `AppNavigation` (Q22).+ let onOpenAnnouncement: (TodayAnnouncement) -> Void /// Q69: at an accessibility size the day chrome scrolls with the list /// instead of standing fixed above it. The same branch `WeekWidget` reads for /// its 4 + 3 wrap, so one setting decides both. @Environment(\.dynamicTypeSize) private var dynamicTypeSize+ /// `today-announcements` Q22: the one seen state, written at the top of the+ /// window. Optional so a preview or a test that does not write it draws no+ /// announcement rather than trapping.+ @Environment(AnnouncementSeenState.self) private var announcements: AnnouncementSeenState? @State private var showingActionableOnly = false @State private var showingDuplicatesOnly = false@@ -133,6 +145,8 @@ struct TodayView: View { selectedEntryID: UUID? = nil, searchFocusRequest: Int = 0, showsSky: Bool = true,+ libraryHasBeenRead: Bool = false,+ onOpenAnnouncement: @escaping (TodayAnnouncement) -> Void = { _ in }, onSelect: @escaping (UUID) -> Void, onTeach: ((UUID) -> Void)? = nil, onShowDiagnostics: (() -> Void)? = nil,@@ -158,6 +172,8 @@ struct TodayView: View { self.selectedEntryID = selectedEntryID self.searchFocusRequest = searchFocusRequest self.showsSky = showsSky+ self.libraryHasBeenRead = libraryHasBeenRead+ self.onOpenAnnouncement = onOpenAnnouncement self.onSelect = onSelect self.onTeach = onTeach self.onShowDiagnostics = onShowDiagnostics@@ -383,6 +399,10 @@ struct TodayView: View { placement: plan.day.placement, drawsNotedHeader: plan.drawsNotedHeader) return List { chromeRows(plan)+ // Q24: directly after the chrome and before every content section.+ // Above the chrome it would sit over the search field, and at the+ // accessibility sizes the chrome *is* the list's first section.+ announcementSection(plan) switch plan.day.placement { case .releasesFirst: releasesSection(plan, accent: accents.releases)@@ -401,6 +421,40 @@ struct TodayView: View { .accessibilityIdentifier("recent-list") } + // MARK: - The announcement row (`today-announcements`)++ /// The one announcement this screen may show, in a **headerless section of+ /// its own** (Q2): under the noted header it would read as something the+ /// reader captured.+ ///+ /// Drawn on the day list only — `spanningList` never calls this. A screen+ /// spanning every day is a search or a banner filter, and neither is a+ /// place to announce anything (Q2, Q20 for the guide's exception, which is+ /// the empty-library branch and draws the day list).+ @ViewBuilder+ private func announcementSection(_ plan: TodayDisplayPlan) -> some View {+ if let announcement = announcement(plan) {+ Section {+ TodayAnnouncementRow(announcement: announcement, onOpen: onOpenAnnouncement)+ .constellationListRow()+ }+ }+ }++ /// The rule's answer for this screen as it stands.+ ///+ /// "No entries" is the empty-library branch, which is the test the settled+ /// message uses; "one current day" is `!spansAllDays` with the selected day+ /// equal to the current one.+ private func announcement(_ plan: TodayDisplayPlan) -> TodayAnnouncement? {+ announcements?.announcement(+ libraryHasBeenRead: libraryHasBeenRead,+ libraryHasNoEntries: plan.branch == .emptyLibrary,+ isAwaitingFirstSync: sync.isAwaitingFirstSync,+ selectedDayHasNotedSection: plan.day.noted != nil,+ showsSingleCurrentDay: !plan.spansAllDays && selectedDay == currentDay)+ }+ /// Req 5.1: the works due on the selected day, one row each. @ViewBuilder private func releasesSection(@@ -489,7 +543,7 @@ struct TodayView: View { if plan.branch == .emptyLibrary { // In place of the section, header and all: a reader with nothing // captured is told that, rather than shown an empty day.- Section { emptyBranch.constellationListRow() }+ emptyLibrarySection(plan) } else { Section { if noted.rows.isEmpty {@@ -561,6 +615,29 @@ struct TodayView: View { .constellationListRow() } + /// The empty-library branch's stand-in for the noted section — **unless the+ /// getting-started row is drawn above**, in which case it draws nothing and+ /// the row is the whole of what the reader is told (`today-announcements`+ /// Q5, Q20).+ ///+ /// It keys off `announcement(plan)`, the same answer the row itself keys+ /// off, and deliberately **not** off `plan.branch` alone: a build that+ /// bundles no guide, or whose guide will not read, draws no row (Q29), and a+ /// branch-only condition would leave such a library showing neither the row+ /// nor the message it replaces. The arriving case never reaches the guard —+ /// the rule refuses a row while a library is arriving — so that message is+ /// untouched.+ ///+ /// The condition itself is `TodayAnnouncements.drawsEmptyLibraryMessage`,+ /// so a test holds it rather than this comment.+ @ViewBuilder+ private func emptyLibrarySection(_ plan: TodayDisplayPlan) -> some View {+ if TodayAnnouncements.drawsEmptyLibraryMessage(+ branch: plan.branch, announcement: announcement(plan)) {+ Section { emptyBranch.constellationListRow() }+ }+ }+ /// Req 6.5: an empty library that has never received anything from iCloud is /// still filling, and presenting it as settled is what the requirement /// forbids. Once one import has completed the ordinary branch returns, for
diff --git a/Asterism/AsterismTests/AnnouncementDocumentTests.swift b/Asterism/AsterismTests/AnnouncementDocumentTests.swiftnew file mode 100644index 00000000..fd8e9c2f--- /dev/null+++ b/Asterism/AsterismTests/AnnouncementDocumentTests.swift@@ -0,0 +1,208 @@+import Foundation+import Testing++@testable import Asterism++/// Which bundled files are documents (`today-announcements` Q9, Q26), and how a+/// document's Markdown splits into the blocks the renderer draws (Decision 1).+@Suite("Announcement documents")+struct AnnouncementDocumentTests {+ // MARK: - The catalog++ @Test("the three filename shapes are recognised")+ func filenamesAreRecognised() {+ #expect(+ AnnouncementCatalog.document(forFilename: "release-notes-0.7.0.md")+ == .releaseNote(version: "0.7.0"))+ #expect(+ AnnouncementCatalog.document(forFilename: "getting-started.md") == .gettingStarted)+ #expect(+ AnnouncementCatalog.document(forFilename: "getting-started-mac.md")+ == .gettingStartedMac)+ }++ /// Q26: reading `-beta` as zero would collide `1.1-beta` with `1.1`, so such+ /// a file is not a document at all — never listed, never a row.+ @Test("a version that is not dotted integers is ignored")+ func nonNumericVersionIsIgnored() {+ #expect(AnnouncementCatalog.document(forFilename: "release-notes-1.1-beta.md") == nil)+ #expect(AnnouncementCatalog.document(forFilename: "release-notes-latest.md") == nil)+ #expect(AnnouncementCatalog.document(forFilename: "release-notes-.md") == nil)+ }++ @Test("an unrelated file is not a document")+ func unrelatedFileIsIgnored() {+ #expect(AnnouncementCatalog.document(forFilename: "README.md") == nil)+ #expect(AnnouncementCatalog.document(forFilename: "release-notes-0.7.0.txt") == nil)+ }++ @Test("a document names the file it is bundled as")+ func documentNamesItsFile() {+ #expect(AnnouncementDocument.releaseNote(version: "0.7.0").filename+ == "release-notes-0.7.0.md")+ #expect(AnnouncementDocument.releaseNote(version: "0.7.0").resourceName+ == "release-notes-0.7.0")+ #expect(AnnouncementDocument.gettingStartedMac.filename == "getting-started-mac.md")+ }++ @Test("a catalog sorts its versions newest first and ignores what it cannot read")+ func catalogSortsAndFilters() {+ let catalog = AnnouncementCatalog(filenames: [+ "release-notes-0.9.0.md", "release-notes-0.10.0.md", "release-notes-0.7.0.md",+ "release-notes-1.1-beta.md", "getting-started.md", "Info.plist",+ ])+ #expect(catalog.releaseNoteVersions == ["0.10.0", "0.9.0", "0.7.0"])+ #expect(catalog.newestReleaseNoteVersion == "0.10.0")+ #expect(catalog.hasGettingStarted)+ #expect(catalog.hasGettingStartedMac == false)+ #expect(catalog.otherReleaseNoteVersions(than: "0.9.0") == ["0.10.0", "0.7.0"])+ }++ /// Q16: the Mac variant on the Mac, the shared guide everywhere else —+ /// including the iPad, which shares the phone's share sheet.+ @Test("the Mac takes the Mac variant and nothing else does")+ func macVariantIsTheMacs() {+ let both = AnnouncementCatalog(filenames: [+ "getting-started.md", "getting-started-mac.md",+ ])+ #expect(both.gettingStartedDocument(isMac: true) == .gettingStartedMac)+ #expect(both.gettingStartedDocument(isMac: false) == .gettingStarted)++ let sharedOnly = AnnouncementCatalog(filenames: ["getting-started.md"])+ #expect(sharedOnly.gettingStartedDocument(isMac: true) == .gettingStarted)++ #expect(AnnouncementCatalog(filenames: []).gettingStartedDocument(isMac: false) == nil)+ }++ // MARK: - The splitter++ @Test("headings strip their markers and keep their level")+ func headings() {+ #expect(+ MarkdownBlocks.blocks(from: "# One\n\n## Two\n\n### Three") == [+ .heading(level: 1, text: "One"),+ .heading(level: 2, text: "Two"),+ .heading(level: 3, text: "Three"),+ ])+ }++ @Test("consecutive lines join with a space and a blank line ends the block")+ func paragraphs() {+ #expect(+ MarkdownBlocks.blocks(from: "One line\nand its second.\n\nA new one.") == [+ .paragraph("One line and its second."),+ .paragraph("A new one."),+ ])+ }++ @Test("both bullet markers make one unordered list")+ func unorderedLists() {+ #expect(+ MarkdownBlocks.blocks(from: "- first\n- second\n* third") == [+ .unorderedList(["first", "second", "third"])+ ])+ }++ /// The source's own numbers are discarded: the list draws 1…n, which is what+ /// "ordered lists numbered from 1" means for a document that writes `1.`+ /// three times.+ @Test("an ordered list keeps its items in order whatever the source numbered them")+ func orderedLists() {+ #expect(+ MarkdownBlocks.blocks(from: "1. first\n1. second\n3. third") == [+ .orderedList(["first", "second", "third"])+ ])+ }++ @Test("a list ends where the next kind of line begins")+ func listsEnd() {+ #expect(+ MarkdownBlocks.blocks(from: "- item\nA sentence.\n1. numbered") == [+ .unorderedList(["item"]),+ .paragraph("A sentence."),+ .orderedList(["numbered"]),+ ])+ }++ @Test("an image on its own line yields its alt text and asset name")+ func images() {+ #expect(+ MarkdownBlocks.blocks(from: "") == [+ .image(alt: "The share sheet", asset: "share-sheet")+ ])+ }++ /// An image inside a sentence is inline, which the subset does not cover.+ @Test("an image with text beside it stays literal")+ func inlineImageIsLiteral() {+ #expect(+ MarkdownBlocks.blocks(from: "Look:  there.") == [+ .paragraph("Look:  there.")+ ])+ }++ /// Decision 1's consequence, stated as a test: a document that strays+ /// outside the subset is legible rather than lost.+ @Test(+ "a block outside the subset renders as a paragraph of its literal text",+ arguments: [+ ("| a | b |\n| - | - |", "| a | b | | - | - |"),+ ("```swift\nlet x = 1\n```", "```swift let x = 1 ```"),+ ("> quoted", "> quoted"),+ ("<p>raw</p>", "<p>raw</p>"),+ ("#### too deep", "#### too deep"),+ ("#hashtag", "#hashtag"),+ ])+ func outsideTheSubset(source: String, expected: String) {+ #expect(MarkdownBlocks.blocks(from: source) == [.paragraph(expected)])+ }++ /// A nested item keeps its indentation, because what it renders as is the+ /// text that was written.+ @Test("a nested list item is literal text under its list")+ func nestedListItem() {+ #expect(+ MarkdownBlocks.blocks(from: "- top\n - nested") == [+ .unorderedList(["top"]),+ .paragraph(" - nested"),+ ])+ }++ @Test("an empty document has no blocks")+ func emptyDocument() {+ #expect(MarkdownBlocks.blocks(from: "").isEmpty)+ #expect(MarkdownBlocks.blocks(from: "\n \n\n").isEmpty)+ }++ @Test("a whole document splits into every kind of block")+ func wholeDocument() {+ let source = """+ # Version 0.7.0++ This release adds announcements.+ They appear on Today.++ ## What is new++ - A release note+ - A getting-started guide++ ++ ### Steps++ 1. Open Today+ 2. Tap the row+ """+ #expect(+ MarkdownBlocks.blocks(from: source) == [+ .heading(level: 1, text: "Version 0.7.0"),+ .paragraph("This release adds announcements. They appear on Today."),+ .heading(level: 2, text: "What is new"),+ .unorderedList(["A release note", "A getting-started guide"]),+ .image(alt: "A release note row", asset: "release-note-row"),+ .heading(level: 3, text: "Steps"),+ .orderedList(["Open Today", "Tap the row"]),+ ])+ }+}
diff --git a/Asterism/AsterismTests/AnnouncementDocumentViewTests.swift b/Asterism/AsterismTests/AnnouncementDocumentViewTests.swiftnew file mode 100644index 00000000..2ea45bd3--- /dev/null+++ b/Asterism/AsterismTests/AnnouncementDocumentViewTests.swift@@ -0,0 +1,56 @@+import Foundation+import Testing++@testable import Asterism++/// What the rendered document says around the Markdown: the list of other+/// bundled versions (`today-announcements` Q7, Q25), the inline-styling+/// fallback, and the name a UI journey finds the view by.+@Suite("Announcement document view")+struct AnnouncementDocumentViewTests {+ private let catalog = AnnouncementCatalog(filenames: [+ "release-notes-0.7.0.md", "release-notes-0.9.0.md", "release-notes-0.10.0.md",+ "getting-started.md",+ ])++ /// Q7: every *other* bundled version, newest first by numeric comparison —+ /// which is why `0.10.0` leads `0.9.0` rather than following it.+ @Test("the list holds every other bundled version, newest first")+ func listContentsAndOrder() {+ #expect(catalog.otherReleaseNoteVersions(than: "0.7.0") == ["0.10.0", "0.9.0"])+ #expect(catalog.otherReleaseNoteVersions(than: "0.10.0") == ["0.9.0", "0.7.0"])+ }++ /// A version with no bundled note is never listed, so it can never produce a+ /// row the reader taps into nothing.+ @Test("an unbundled version is never listed")+ func unbundledVersionIsNotListed() {+ #expect(catalog.otherReleaseNoteVersions(than: "0.8.0").contains("0.8.0") == false)+ #expect(catalog.otherReleaseNoteVersions(than: "0.8.0") == ["0.10.0", "0.9.0", "0.7.0"])+ }++ /// The getting-started guide is not one of a series, so nothing is listed+ /// under it.+ @Test("a catalog with one note lists nothing under it")+ func singleNoteListsNothing() {+ let single = AnnouncementCatalog(filenames: ["release-notes-0.7.0.md"])+ #expect(single.otherReleaseNoteVersions(than: "0.7.0").isEmpty)+ }++ @Test("inline styling falls back to the plain string rather than throwing")+ func inlineStylingFallsBack() {+ #expect(String(MarkdownDocumentView.inline("plain text").characters) == "plain text")+ // The markers are consumed, the words survive.+ #expect(String(MarkdownDocumentView.inline("**bold**").characters) == "bold")+ #expect(String(MarkdownDocumentView.inline("a [link](x) here").characters)+ == "a link here")+ }++ /// The production half of the contract with the UI suites: a marker layer,+ /// because an identifier on the scroll view would rename the version+ /// buttons inside it.+ @Test("the document view carries the announcement-document marker")+ func documentMarker() {+ #expect(LayoutMarker.announcementDocument == "announcement-document")+ }+}
diff --git a/Asterism/AsterismTests/AnnouncementSeenStateTests.swift b/Asterism/AsterismTests/AnnouncementSeenStateTests.swiftnew file mode 100644index 00000000..d1a09613--- /dev/null+++ b/Asterism/AsterismTests/AnnouncementSeenStateTests.swift@@ -0,0 +1,353 @@+import Foundation+import Testing++@testable import Asterism++/// The per-device last-seen version (`today-announcements` Decision 2, Q8,+/// Q12), and the pin a seeded UI-test launch starts from (Q14).+///+/// Every test owns a throwaway `UserDefaults` suite, which is what makes+/// persistence itself assertable here: a seeded launch rewrites the key, so no+/// UI journey can prove that a value survives.+@Suite("Announcement seen state")+@MainActor+struct AnnouncementSeenStateTests {+ /// The bundle the unit bundle runs in declares its own version; the tests+ /// below need one they chose, so they read it from the state they made.+ private func state(_ defaults: UserDefaults) -> AnnouncementSeenState {+ AnnouncementSeenState(defaults: defaults, bundle: .main)+ }++ @Test("a fresh install has no last-seen version")+ func freshInstallHasNothing() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ #expect(state(defaults).lastSeenVersion == nil)+ }+ }++ @Test("a stored version survives a new instance")+ func storedVersionSurvives() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let first = state(defaults)+ first.recordReleaseNoteSeen()+ #expect(first.lastSeenVersion == first.currentVersion)++ let second = state(defaults)+ #expect(second.lastSeenVersion == first.currentVersion)+ }+ }++ /// The observed value moves with the store, because the row watches it: a+ /// `UserDefaults` write triggers no Observation of its own (Q22).+ @Test("storing updates the observed value and removes the row")+ func storingRemovesTheRow() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ defaults.set("0.6.0", forKey: AnnouncementSeenState.lastSeenVersionKey)+ let seen = state(defaults)+ #expect(seen.lastSeenVersion == "0.6.0")++ seen.recordReleaseNoteSeen()++ #expect(seen.lastSeenVersion == seen.currentVersion)+ #expect(+ TodayAnnouncements.row(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true,+ lastSeenVersion: seen.lastSeenVersion,+ currentVersion: seen.currentVersion,+ bundledVersions: [seen.currentVersion]) == nil)+ }+ }++ /// Q11's silent store, through the object that owns the key.+ @Test("a read empty library takes the current version once and not again")+ func silentStoreRunsOnce() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = state(defaults)+ #expect(+ seen.storeVersionSilentlyIfNeeded(+ libraryHasBeenRead: true, libraryHasNoEntries: true))+ #expect(seen.lastSeenVersion == seen.currentVersion)+ #expect(+ seen.storeVersionSilentlyIfNeeded(+ libraryHasBeenRead: true, libraryHasNoEntries: true) == false)+ }+ }++ @Test("an unread library stores nothing")+ func unreadLibraryStoresNothing() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = state(defaults)+ #expect(+ seen.storeVersionSilentlyIfNeeded(+ libraryHasBeenRead: false, libraryHasNoEntries: true) == false)+ #expect(seen.lastSeenVersion == nil)+ }+ }++ // MARK: - The seeded launch's pin (Q14)++ private struct Environment: ProcessEnvironmentProviding {+ let environment: [String: String]+ }++ /// The default: every seeded fixture starts having seen the version it is+ /// running, so no journey but the ones that ask for it meets a row.+ @Test("a seeded launch with no variable pins the current version, so no row shows")+ func pinDefaultsToTheCurrentVersion() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ UITestLaunchSupport.pinLastSeenVersion(+ in: defaults,+ currentVersion: "0.7.0",+ environmentProvider: Environment(environment: [:]))++ let seen = state(defaults)+ #expect(seen.lastSeenVersion == "0.7.0")+ #expect(+ TodayAnnouncements.row(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true,+ lastSeenVersion: seen.lastSeenVersion,+ currentVersion: "0.7.0",+ bundledVersions: ["0.7.0"]) == nil)+ }+ }++ @Test("the override names an older version, so the row shows")+ func pinOverrideShowsTheRow() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ UITestLaunchSupport.pinLastSeenVersion(+ in: defaults,+ currentVersion: "0.7.0",+ environmentProvider: Environment(+ environment: [UITestLaunchSupport.lastSeenVersionKey: "0.6.0"]))++ let seen = state(defaults)+ #expect(seen.lastSeenVersion == "0.6.0")+ #expect(+ TodayAnnouncements.row(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true,+ lastSeenVersion: seen.lastSeenVersion,+ currentVersion: "0.7.0",+ bundledVersions: ["0.7.0"]) == .releaseNote(version: "0.7.0"))+ }+ }++ // MARK: - The bundled-document gate++ /// The deviation from the smolspec that ``AnnouncementSeenState/announcement``+ /// makes deliberately: the **rule** says Getting started, and the state drops+ /// the row anyway because this build bundles no guide to open. A row that+ /// opened on "this document could not be read" would be a row that should+ /// not have been there.+ ///+ /// This is also what holds task 8 together — the settled empty-library+ /// message stands down for a row that is actually drawn, never for one this+ /// gate removed. `TodayView.emptyLibrarySection` asks this very function, so+ /// a nil here **is** the message being kept: an empty library on a build with+ /// no bundled guide is shown "No captures yet" exactly as it was before this+ /// feature, rather than neither the row nor the message.+ ///+ /// The bundle is a throwaway one carrying a note and no guide. The app's own+ /// bundle carried no guide until task 8 wrote it; a test that leaned on that+ /// absence would now assert nothing.+ @Test("a getting-started row with no bundled guide is dropped, and the message stays")+ func gettingStartedWithoutADocumentIsDropped() throws {+ try AnnouncementTestSupport.withBundle(+ containing: ["release-notes-0.7.0.md": "# Version 0.7.0\n\nHello.\n"]+ ) { bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.catalog.hasGettingStarted == false)+ // The rule says Getting started; the gate drops it anyway.+ #expect(+ TodayAnnouncements.row(+ libraryHasBeenRead: true,+ libraryHasNoEntries: true,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true,+ lastSeenVersion: seen.lastSeenVersion,+ currentVersion: seen.currentVersion,+ bundledVersions: seen.catalog.releaseNoteVersions) == .gettingStarted)+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: true,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == nil)+ }+ }+ }++ /// Q29's gap, closed in task 8: a guide that is **bundled and empty** used to+ /// pass the Today gate, because the gate consulted a file listing while+ /// Settings read the text. The catalog is now built from documents that read,+ /// so both refuse it — and the empty-library message is kept, as it is for a+ /// guide that was never bundled at all.+ @Test("a bundled but empty guide is refused by Today as well as by Settings")+ func anEmptyGuideIsRefusedEverywhere() throws {+ try AnnouncementTestSupport.withBundle(containing: ["getting-started.md": " \n\n"]) {+ bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.catalog.hasGettingStarted == false)+ #expect(seen.settingsGettingStartedDocument == nil)+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: true,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == nil)+ }+ }+ }++ /// The same bar on the release note, and on the Settings row that opens it:+ /// an empty note file is not a bundled note.+ ///+ /// "Both routes" is asserted rather than implied. The Settings row is the+ /// first expectation; the Today route is the last two — the gate refuses the+ /// document, and the rule refuses the row when it is asked with the catalog+ /// this bundle produced. That last one is the isolating claim: had the file+ /// read, `releaseNoteVersions` would hold `0.7.0` and the rule would return+ /// the row.+ @Test("a bundled but empty release note is refused by both routes")+ func anEmptyReleaseNoteIsRefusedEverywhere() throws {+ try AnnouncementTestSupport.withBundle(containing: ["release-notes-0.7.0.md": "\n"]) {+ bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.catalog.releaseNoteVersions.isEmpty)+ #expect(seen.settingsReleaseNoteDocument == nil)++ #expect(seen.document(for: .releaseNote(version: "0.7.0")) == nil)+ #expect(+ TodayAnnouncements.row(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true,+ lastSeenVersion: nil,+ currentVersion: "0.7.0",+ bundledVersions: seen.catalog.releaseNoteVersions) == nil)+ // …and the state's own route, which is what Today calls.+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == nil)+ }+ }+ }++ /// Q16's variant choice, asked of the state rather than of the catalog: the+ /// Mac gets its own file where one is bundled, every other platform gets the+ /// shared guide, and a build with only the shared guide gives the Mac that.+ @Test("the Mac opens the Mac variant and the iPad the shared guide")+ func theMacVariantIsChosenOnTheMacOnly() throws {+ try AnnouncementTestSupport.withBundle(containing: [+ "getting-started.md": "# Getting started\n\nShare a page.\n",+ "getting-started-mac.md": "# Getting started\n\nUse the Share menu.\n",+ ]) { bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.document(for: .gettingStarted, isMac: true) == .gettingStartedMac)+ #expect(seen.document(for: .gettingStarted, isMac: false) == .gettingStarted)+ }+ }++ try AnnouncementTestSupport.withBundle(+ containing: ["getting-started.md": "# Getting started\n\nShare.\n"]+ ) { bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.document(for: .gettingStarted, isMac: true) == .gettingStarted)+ #expect(seen.document(for: .gettingStarted, isMac: false) == .gettingStarted)+ }+ }+ }++ /// The other side of the same gate: bundle a guide and the row is returned.+ @Test("a getting-started row is returned where the guide is bundled")+ func gettingStartedWithADocumentShows() throws {+ try AnnouncementTestSupport.withBundle(+ containing: ["getting-started.md": "# Getting started\n\nCapture a page.\n"]+ ) { bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.catalog.hasGettingStarted)+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: true,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == .gettingStarted)+ // Still nothing while the library is arriving: the gate never+ // adds a row the rule refused.+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: true,+ isAwaitingFirstSync: true,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == nil)+ }+ }+ }++ /// The release-note arm passes the gate because the rule already asked the+ /// same catalog: a version with no bundled note never becomes a row in the+ /// first place (Q9), so the gate is a second lock on the same door rather+ /// than a different one.+ @Test("a release note whose file this build carries survives the gate")+ func releaseNoteWithADocumentShows() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = state(defaults)+ #expect(+ seen.catalog.releaseNoteVersions.contains(seen.currentVersion),+ "This build should bundle its own note")+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == .releaseNote(version: seen.currentVersion))+ }+ }++ /// A bundle carrying no note at all: nothing to announce, nothing announced.+ @Test("a build with no bundled note shows no release-note row")+ func releaseNoteWithoutADocumentIsDropped() throws {+ try AnnouncementTestSupport.withBundle(containing: [:]) { bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(seen.catalog.releaseNoteVersions.isEmpty)+ #expect(+ seen.announcement(+ libraryHasBeenRead: true,+ libraryHasNoEntries: false,+ isAwaitingFirstSync: false,+ selectedDayHasNotedSection: true,+ showsSingleCurrentDay: true) == nil)+ }+ }+ }+}
diff --git a/Asterism/AsterismTests/AnnouncementTestSupport.swift b/Asterism/AsterismTests/AnnouncementTestSupport.swiftnew file mode 100644index 00000000..0edf0029--- /dev/null+++ b/Asterism/AsterismTests/AnnouncementTestSupport.swift@@ -0,0 +1,52 @@+import Foundation+import Testing++@testable import Asterism++/// The two throwaway fixtures the announcement suites are built on+/// (`today-announcements`): a `UserDefaults` suite nothing else can see, and a+/// bundle holding exactly the files a test names.+///+/// Both suites need both, and both had their own copy — including the same+/// `Issue.record` sentence written twice. One copy each, here.+@MainActor+enum AnnouncementTestSupport {+ /// A defaults suite of its own per test, removed afterwards so nothing+ /// leaks into the next one or into the host app's own defaults.+ static func withThrowawayDefaults(_ body: (UserDefaults) -> Void) {+ let name = "announcements.tests.\(UUID().uuidString)"+ guard let defaults = UserDefaults(suiteName: name) else {+ Issue.record("Could not make a throwaway defaults suite")+ return+ }+ defer { defaults.removePersistentDomain(forName: name) }+ body(defaults)+ }++ /// A throwaway bundle holding the files a test names, so a gate can be asked+ /// about a document *this* build does not bundle — or about a build that+ /// bundles nothing at all, which `[:]` gives.+ ///+ /// The files are written before the `Bundle` is made: a bundle caches what+ /// it found the first time it was asked for it.+ static func withBundle(containing files: [String: String], _ body: (Bundle) -> Void) throws {+ let root = FileManager.default.temporaryDirectory+ .appending(path: "announcements-\(UUID().uuidString).bundle")+ #if os(macOS)+ let resources = root.appending(path: "Contents/Resources")+ #else+ let resources = root+ #endif+ try FileManager.default.createDirectory(at: resources, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: root) }+ for (name, contents) in files {+ try contents.write(+ to: resources.appending(path: name), atomically: true, encoding: .utf8)+ }+ guard let bundle = Bundle(url: root) else {+ Issue.record("Could not make a throwaway bundle")+ return+ }+ body(bundle)+ }+}
diff --git a/Asterism/AsterismTests/BundledAnnouncementTests.swift b/Asterism/AsterismTests/BundledAnnouncementTests.swiftnew file mode 100644index 00000000..aac2cefb--- /dev/null+++ b/Asterism/AsterismTests/BundledAnnouncementTests.swift@@ -0,0 +1,257 @@+import Foundation+import Testing++@testable import Asterism++/// What the *built app* carries (`today-announcements` task 5).+///+/// The unit bundle runs in the app as its host, so `Bundle.main` here is+/// `Asterism.app` — which makes this the one place a test can ask whether a+/// document was copied into the product and whether the app icon resolves for+/// the row's cover slot. Both are claims about the build, not about a value.+@Suite("Bundled announcements")+@MainActor+struct BundledAnnouncementTests {+ /// The synchronized folder group copies `Announcements/Documents/*.md` flat+ /// into the bundle root, which is why the scheme is a filename prefix (Q9).+ /// If this fails, the file was not copied — not that the catalog is wrong.+ @Test("the 0.7.0 release note is in the built bundle")+ func releaseNoteIsBundled() {+ let catalog = BundledAnnouncements.catalog()+ #expect(catalog.releaseNoteVersions.contains("0.7.0"))+ #expect(BundledAnnouncements.text(for: .releaseNote(version: "0.7.0")) != nil)+ }++ /// Task 8's two guides, and the same claim about the build: the Mac variant+ /// is a file of its own (Q16), and a missing one would silently fall back to+ /// the shared guide rather than fail anything.+ @Test("both getting-started guides are in the built bundle")+ func guidesAreBundled() {+ let catalog = BundledAnnouncements.catalog()+ #expect(catalog.hasGettingStarted)+ #expect(catalog.hasGettingStartedMac)+ #expect(BundledAnnouncements.text(for: .gettingStarted) != nil)+ #expect(BundledAnnouncements.text(for: .gettingStartedMac) != nil)+ }++ /// Each guide opens on its own heading, so the reader knows which of the two+ /// they are reading, and neither is a stub.+ @Test("each guide opens on a heading and carries real steps")+ func guidesReadAsDocuments() throws {+ for document in [AnnouncementDocument.gettingStarted, .gettingStartedMac] {+ let text = try #require(BundledAnnouncements.text(for: document))+ let blocks = MarkdownBlocks.blocks(from: text)+ #expect(+ blocks.first == .heading(level: 1, text: "Getting started"),+ "\(document.filename) should open on its title")+ let lists = blocks.filter {+ if case .orderedList = $0 { return true } else { return false }+ }+ #expect(lists.isEmpty == false, "\(document.filename) should carry numbered steps")+ }+ }++ @Test("the bundled note renders as blocks rather than one literal paragraph")+ func bundledNoteSplits() throws {+ let text = try #require(BundledAnnouncements.text(for: .releaseNote(version: "0.7.0")))+ let blocks = MarkdownBlocks.blocks(from: text)+ #expect(blocks.first == .heading(level: 1, text: "Version 0.7.0"))++ // **One** list for the section, not one per bullet. The earlier form of+ // this test asked only whether *some* unordered list existed, which the+ // broken document also satisfied: six hard-wrapped bullets came out as+ // six one-item lists, each trailed by a paragraph of its own+ // continuation line.+ let lists = blocks.compactMap { block -> [String]? in+ if case .unorderedList(let items) = block { return items } else { return nil }+ }+ #expect(lists.count == 1)++ let headingIndex = try #require(+ blocks.firstIndex(of: .heading(level: 2, text: "Also in this release")))+ let section = try #require(blocks.dropFirst(headingIndex + 1).first)+ guard case .unorderedList(let items) = section else {+ Issue.record("The section should open with one unordered list, not \(section)")+ return+ }+ #expect(items.count == 6)+ // …and nothing stray sits between that list and the next heading.+ #expect(+ blocks.dropFirst(headingIndex + 2).first+ == .heading(level: 2, text: "What this version does not do"))+ }++ /// The documents are **written** inside the supported subset, not merely+ /// read by it (Decision 1: the splitter has no lazy continuation, so a+ /// hard-wrapped list item's second line is not part of the item).+ ///+ /// Two tells, because the first one alone lets half the defect through.+ ///+ /// The **source** tell is a list-marker line whose next line is non-blank+ /// and is not a marker of its own: the only reason to write that is lazy+ /// continuation, which this subset does not have. It catches a wrap in+ /// either style, indented or flush left.+ ///+ /// The **block** tell is a paragraph that begins with whitespace: no block+ /// rule claimed the line, so it fell through to the paragraph rule carrying+ /// the indentation it was written with. It catches only an indented wrap,+ /// which is why it is the second check rather than the only one.+ ///+ /// **Counting markers against list items does not work**, and was tried:+ /// each marker still produces a list of its own, so a torn document has as+ /// many items as it has markers. Measured against this splitter, the+ /// flush-left and indented fixtures below both count 2 markers and 2 items.+ ///+ /// Asserted over every bundled document, so a guide added later is held to+ /// the same bar.+ @Test("no bundled document leans on a continuation the subset does not parse")+ func bundledDocumentsStayInsideTheSubset() throws {+ let catalog = BundledAnnouncements.catalog()+ var documents = catalog.releaseNoteVersions.map {+ AnnouncementDocument.releaseNote(version: $0)+ }+ if catalog.hasGettingStarted { documents.append(.gettingStarted) }+ if catalog.hasGettingStartedMac { documents.append(.gettingStartedMac) }+ #expect(documents.isEmpty == false, "No document was bundled to check")++ for document in documents {+ let text = try #require(BundledAnnouncements.text(for: document))+ for wrap in Self.hardWrappedListItems(in: text) {+ Issue.record(+ """+ \(document.filename) line \(wrap.line): a list item is hard-wrapped, \+ and the subset has no lazy continuation to join it back up. \+ After "\(wrap.marker)" came "\(wrap.continuation)".+ """)+ }+ for block in MarkdownBlocks.blocks(from: text) {+ guard case .paragraph(let paragraph) = block else { continue }+ #expect(+ paragraph.first?.isWhitespace != true,+ "\(document.filename): an indented continuation of its own — \(paragraph)")+ }+ }+ }++ /// The guard above, proved against the shape it exists to catch — rather+ /// than by breaking a real guide to watch it go red.+ ///+ /// Both wrap styles, and the one legitimate shape they could be confused+ /// with: a well-formed list with a paragraph after it.+ @Test("the subset check catches a hard-wrapped list item in either wrap style")+ func theSubsetCheckCatchesAHardWrappedItem() {+ let flushLeft = """+ - **Releasing** lists the works due to release on that day. A work appears+ here only while it is ongoing and you are reading it.+ - **Noted** lists what you captured on that day.+ """+ let indented = """+ 1. Open any page in Safari and tap the share button, then scroll the row+ of apps along to its end.+ 2. Tap **More**.+ """+ let wellFormed = """+ - One item, whole, on one physical line.+ - Another item.++ A paragraph that legitimately follows the list.+ """++ #expect(Self.hardWrappedListItems(in: flushLeft).count == 1)+ #expect(Self.hardWrappedListItems(in: indented).count == 1)+ #expect(Self.hardWrappedListItems(in: wellFormed).isEmpty)++ // …and the block tell on its own would have passed the flush-left one,+ // which is why the source tell above is the primary check.+ #expect(Self.blocksHaveAnIndentedParagraph(flushLeft) == false)+ #expect(Self.blocksHaveAnIndentedParagraph(indented))+ }++ // MARK: - The two tells++ private struct HardWrap {+ let line: Int+ let marker: String+ let continuation: String+ }++ /// Every list-marker line the document continues on the next physical line.+ ///+ /// **The rules are the splitter's own**, asked of a raw source line rather+ /// than copied here: a copy would keep passing after a marker was added to+ /// `MarkdownBlocks` while quietly no longer seeing those lines, which is the+ /// shape of the defect this guard exists for.+ private static func hardWrappedListItems(in text: String) -> [HardWrap] {+ let lines = text.split(separator: "\n", omittingEmptySubsequences: false)+ .map { MarkdownBlocks.trailingTrimmed(String($0)) }+ var found: [HardWrap] = []+ for index in lines.indices.dropLast()+ where MarkdownBlocks.isListMarkerLine(lines[index]) {+ let next = lines[index + 1]+ guard next.trimmingCharacters(in: .whitespaces).isEmpty == false else { continue }+ guard MarkdownBlocks.isListMarkerLine(next) == false else { continue }+ found.append(+ HardWrap(line: index + 2, marker: lines[index], continuation: next))+ }+ return found+ }++ private static func blocksHaveAnIndentedParagraph(_ text: String) -> Bool {+ MarkdownBlocks.blocks(from: text).contains { block in+ guard case .paragraph(let paragraph) = block else { return false }+ return paragraph.first?.isWhitespace == true+ }+ }++ /// The row's cover slot (Q3). The risk this test exists for: an Icon+ /// Composer `.icon` file is not an asset-catalog image, so the icon is+ /// reached through what the bundle *declares* — `CFBundleIcons`' primary+ /// icon files (Q27) — rather than by a name typed here. A failure means the+ /// row would draw an empty slot and the fallback needs images from the+ /// owner.+ @Test("the app icon resolves for the announcement row's cover slot")+ func appIconResolves() throws {+ let icon = try #require(+ PlatformImages.appIcon(), "The bundle's primary icon did not load by name")+ #expect(icon.pointSize.width > 0)+ #expect(icon.pointSize.height > 0)+ }++ /// Settings' Release notes row opens the newest bundled note (Q17), and is+ /// **hidden** where nothing is bundled — the row cannot exist without+ /// something behind it.+ @Test("the Settings row opens the newest bundled note, and hides without one")+ func settingsRowFollowsTheBundle() throws {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let app = AnnouncementSeenState(defaults: defaults)+ #expect(app.settingsReleaseNoteDocument == .releaseNote(version: "0.7.0"))+ }++ // A bundle with no documents in it at all: the row is not drawn.+ try AnnouncementTestSupport.withBundle(containing: [:]) { bundle in+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let none = AnnouncementSeenState(defaults: defaults, bundle: bundle)+ #expect(none.settingsReleaseNoteDocument == nil)+ }+ }+ }++ /// The seen state reads the same bundle the row draws from, so a build+ /// whose version moved without its note is a build with no row.+ @Test("the seen state reads this build's version and catalog")+ func seenStateReadsTheBundle() {+ AnnouncementTestSupport.withThrowawayDefaults { defaults in+ let seen = AnnouncementSeenState(defaults: defaults)+ #expect(seen.currentVersion.isEmpty == false)+ #expect(seen.catalog.releaseNoteVersions.contains("0.7.0"))+ #expect(+ seen.document(for: .releaseNote(version: "0.7.0"))+ == .releaseNote(version: "0.7.0"))+ // Since task 8 the guide is bundled, so the state claims to draw it —+ // and claims the Mac's variant on the Mac (Q16).+ #expect(seen.document(for: .gettingStarted, isMac: false) == .gettingStarted)+ #expect(seen.document(for: .gettingStarted, isMac: true) == .gettingStartedMac)+ #expect(seen.settingsGettingStartedDocument != nil)+ }+ }+}
diff --git a/Asterism/AsterismTests/TodayAnnouncementsTests.swift b/Asterism/AsterismTests/TodayAnnouncementsTests.swiftnew file mode 100644index 00000000..20c16057--- /dev/null+++ b/Asterism/AsterismTests/TodayAnnouncementsTests.swift@@ -0,0 +1,240 @@+import Foundation+import Testing++@testable import Asterism++/// The rules behind Today's announcement row (`today-announcements`): which row+/// shows, when the current version is stored without showing one, and how two+/// version strings order.+@Suite("Today announcements")+struct TodayAnnouncementsTests {+ /// The inputs of a device whose library holds entries, showing the current+ /// day, with a note bundled for the version it is running and nothing stored+ /// — the release note's case. Every test below states only what it changes.+ private func row(+ libraryHasBeenRead: Bool = true,+ libraryHasNoEntries: Bool = false,+ isAwaitingFirstSync: Bool = false,+ selectedDayHasNotedSection: Bool = true,+ showsSingleCurrentDay: Bool = true,+ lastSeenVersion: String? = nil,+ currentVersion: String = "0.7.0",+ bundledVersions: [String] = ["0.7.0"]+ ) -> TodayAnnouncement? {+ TodayAnnouncements.row(+ libraryHasBeenRead: libraryHasBeenRead,+ libraryHasNoEntries: libraryHasNoEntries,+ isAwaitingFirstSync: isAwaitingFirstSync,+ selectedDayHasNotedSection: selectedDayHasNotedSection,+ showsSingleCurrentDay: showsSingleCurrentDay,+ lastSeenVersion: lastSeenVersion,+ currentVersion: currentVersion,+ bundledVersions: bundledVersions)+ }++ // MARK: - The gate (Q21)++ /// Q21: an empty Today before the first publication proves nothing about the+ /// library, and neither the row nor the store may act on it.+ @Test("an unread library shows no row, however empty it looks")+ func unreadLibraryShowsNothing() {+ #expect(row(libraryHasBeenRead: false, libraryHasNoEntries: true) == nil)+ #expect(row(libraryHasBeenRead: false) == nil)+ }++ @Test("an unread library stores nothing")+ func unreadLibraryStoresNothing() {+ #expect(+ TodayAnnouncements.storesVersionSilently(+ libraryHasBeenRead: false, libraryHasNoEntries: true, lastSeenVersion: nil)+ == false)+ }++ // MARK: - Getting started (Q5, Q20)++ @Test("a settled empty library on a day with a noted section shows getting started")+ func settledEmptyShowsGettingStarted() {+ #expect(row(libraryHasNoEntries: true) == .gettingStarted)+ }++ /// Q20: the empty-library branch ignores the search field by design, so the+ /// guide shows whatever is typed — it stands where the settled message+ /// stands, and that message ignores it too.+ @Test("getting started ignores the search field and the single-day rule")+ func gettingStartedIgnoresSearch() {+ #expect(row(libraryHasNoEntries: true, showsSingleCurrentDay: false) == .gettingStarted)+ }++ /// Q5: an arriving library may be full on another device, so nothing is+ /// announced about it.+ @Test("an arriving empty library shows nothing")+ func arrivingEmptyShowsNothing() {+ #expect(row(libraryHasNoEntries: true, isAwaitingFirstSync: true) == nil)+ }++ /// A future day draws no noted section, so there is nowhere for the message+ /// this row replaces to have been.+ @Test("a day with no noted section shows nothing")+ func futureDayShowsNothing() {+ #expect(row(libraryHasNoEntries: true, selectedDayHasNotedSection: false) == nil)+ }++ /// Q6: at most one row, and the guide wins. The release note's every+ /// condition holds here.+ @Test("getting started beats the release note")+ func gettingStartedBeatsReleaseNote() {+ #expect(+ row(libraryHasNoEntries: true, lastSeenVersion: "0.6.0") == .gettingStarted)+ }++ // MARK: - The release note (Q2, Q9, Q10)++ @Test("a library with entries and an unseen bundled note shows the release note")+ func unseenNoteShowsReleaseNote() {+ #expect(row() == .releaseNote(version: "0.7.0"))+ #expect(row()?.title == "Version 0.7.0")+ }++ @Test("a stored version equal to the current one shows nothing")+ func seenNoteShowsNothing() {+ #expect(row(lastSeenVersion: "0.7.0") == nil)+ }++ /// Q10: inequality, not ordering. A reader moved back to an older build is+ /// shown that build's note.+ @Test("a downgrade counts as a change")+ func downgradeShowsReleaseNote() {+ #expect(+ row(lastSeenVersion: "0.8.0", currentVersion: "0.7.0", bundledVersions: ["0.7.0"])+ == .releaseNote(version: "0.7.0"))+ }++ /// Q9: a release without a note file announces nothing.+ @Test("a current version with no bundled note shows nothing")+ func unbundledVersionShowsNothing() {+ #expect(row(currentVersion: "0.8.0", bundledVersions: ["0.7.0"]) == nil)+ }++ /// Q2: the note sits on the current day only, and a search or a banner+ /// filter takes the screen off it.+ @Test("a searched or filtered screen shows no release note")+ func spanningScreenShowsNothing() {+ #expect(row(showsSingleCurrentDay: false) == nil)+ }++ // MARK: - The message the row replaces (Q5, Q20, Q29)++ /// Today's settled empty-library message stands down for a getting-started+ /// row **that is drawn**, and for nothing else.+ ///+ /// The case that matters is the third: an empty library with no row — a+ /// build bundling no guide, or one whose guide will not read (Q29). Writing+ /// the screen's condition as `branch != .emptyLibrary` would draw neither+ /// the row nor the message and pass every other test in the repo, which is+ /// what this one exists to stop.+ @Test("the empty-library message stands down only for a drawn getting-started row")+ func theMessageStandsDownOnlyForADrawnRow() {+ #expect(+ TodayAnnouncements.drawsEmptyLibraryMessage(+ branch: .emptyLibrary, announcement: .gettingStarted) == false)+ #expect(+ TodayAnnouncements.drawsEmptyLibraryMessage(+ branch: .emptyLibrary, announcement: nil),+ "An empty library with no row keeps the message it would have replaced")+ // Not reachable through the rule — Getting started wins on an empty+ // library (Q6) — but the message belongs to the branch, not to the row's+ // absence, so a release note must not take it away either.+ #expect(+ TodayAnnouncements.drawsEmptyLibraryMessage(+ branch: .emptyLibrary, announcement: .releaseNote(version: "0.7.0")))++ // No other branch has this message at all.+ for branch in [TodayDisplayPlan.Branch.list, .searchMiss] {+ #expect(+ TodayAnnouncements.drawsEmptyLibraryMessage(+ branch: branch, announcement: nil) == false)+ #expect(+ TodayAnnouncements.drawsEmptyLibraryMessage(+ branch: branch, announcement: .gettingStarted) == false)+ }+ }++ // MARK: - The silent store (Q11)++ @Test("a read empty library with nothing stored stores the version, arriving or settled")+ func emptyLibraryStoresSilently() {+ #expect(+ TodayAnnouncements.storesVersionSilently(+ libraryHasBeenRead: true, libraryHasNoEntries: true, lastSeenVersion: nil))+ }++ @Test("a library with entries stores nothing")+ func libraryWithEntriesStoresNothing() {+ #expect(+ TodayAnnouncements.storesVersionSilently(+ libraryHasBeenRead: true, libraryHasNoEntries: false, lastSeenVersion: nil)+ == false)+ }++ /// Storing again would rewrite a value the reader's own dismissal set, and+ /// on a downgraded build it would swallow the note the reader is owed.+ @Test("a stored value is never overwritten silently")+ func storedValueIsNotOverwritten() {+ #expect(+ TodayAnnouncements.storesVersionSilently(+ libraryHasBeenRead: true, libraryHasNoEntries: true, lastSeenVersion: "0.6.0")+ == false)+ }++ // MARK: - Version ordering (Q10, Q26)++ @Test("ordering is numeric per component, not lexical")+ func orderingIsNumeric() {+ #expect(TodayAnnouncements.isVersion("0.10.0", newerThan: "0.9.0"))+ #expect(TodayAnnouncements.isVersion("0.9.0", newerThan: "0.10.0") == false)+ #expect(+ TodayAnnouncements.sortedNewestFirst(["0.9.0", "0.10.0", "1.0.0", "0.7.0"])+ == ["1.0.0", "0.10.0", "0.9.0", "0.7.0"])+ }++ @Test("a missing component reads as zero")+ func missingComponentIsZero() {+ #expect(TodayAnnouncements.isVersion("0.7", newerThan: "0.7.0") == false)+ #expect(TodayAnnouncements.isVersion("0.7.0", newerThan: "0.7") == false)+ #expect(TodayAnnouncements.isVersion("0.7.1", newerThan: "0.7"))+ }++ /// Q26: a suffix read as zero would make `1.1-beta` and `1.1` the same+ /// version, so a file that is not dotted integers is ignored outright.+ @Test("only dotted integers are versions")+ func onlyDottedIntegersAreVersions() {+ #expect(TodayAnnouncements.isDottedIntegers("0.7.0"))+ #expect(TodayAnnouncements.isDottedIntegers("1"))+ #expect(TodayAnnouncements.isDottedIntegers("1.1-beta") == false)+ #expect(TodayAnnouncements.isDottedIntegers("") == false)+ #expect(TodayAnnouncements.isDottedIntegers("1..2") == false)+ #expect(TodayAnnouncements.isDottedIntegers("1.2.") == false)+ #expect(TodayAnnouncements.isDottedIntegers("latest") == false)+ }++ // MARK: - The value itself (Q3)++ @Test("titles and identifiers are exactly what the journeys address")+ func titlesAndIdentifiers() {+ #expect(TodayAnnouncement.gettingStarted.title == "Getting started")+ #expect(+ TodayAnnouncement.gettingStarted.identifier == "today-announcement-getting-started")+ #expect(+ TodayAnnouncement.releaseNote(version: "0.7.0").identifier+ == "today-announcement-release-note")+ }++ /// Q22: the sheet is keyed by the announcement, so moving between bundled+ /// versions inside the document cannot tear it down.+ @Test("a release note's identity does not carry its version")+ func releaseNoteIdentityIgnoresVersion() {+ #expect(+ TodayAnnouncement.releaseNote(version: "0.7.0").id+ == TodayAnnouncement.releaseNote(version: "0.6.0").id)+ }+}
diff --git a/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift b/Asterism/AsterismUITests/AccessibilityJourneyUITests.swiftindex 7d90475e..6d737cb4 100644--- a/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift+++ b/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift@@ -164,8 +164,13 @@ final class AccessibilityJourneyUITests: XCTestCase { let exportLine = app.staticTexts["settings-sync-export-line"] XCTAssertTrue(exportLine.waitForExistence(timeout: 10), "The sync rows should be present")+ // Scrolled for, not asserted in place — the fold moved again. The block+ // below sits at the bottom of a lazy `List`, and+ // `today-announcements` added an About section above Debug exactly as+ // `work-creators` added Creator roles: one more section above means one+ // more row of this block outside the accessibility tree. let importLine = app.staticTexts["settings-sync-import-line"]- XCTAssertTrue(importLine.exists, "Req 8.1 reports the two directions separately")+ scrollUntilPresent(importLine, in: app, "Req 8.1 reports the two directions separately") XCTAssertNotEqual(exportLine.label, importLine.label) // The health and counts rows are the last of the sync block, and the
diff --git a/Asterism/AsterismUITests/AnnouncementUITests.swift b/Asterism/AsterismUITests/AnnouncementUITests.swiftnew file mode 100644index 00000000..2235446a--- /dev/null+++ b/Asterism/AsterismUITests/AnnouncementUITests.swift@@ -0,0 +1,200 @@+import XCTest++/// Today's release-note row and the Settings route to the same document+/// (`today-announcements`), driven from app launch.+///+/// Three things only a journey can prove. The row has to be **there** — the+/// rule, the seen state and the bundled document agree in unit tests, but+/// whether a section was actually added to the day list is a question about a+/// `body`. Tapping it has to open a sheet rather than navigate to an entry. And+/// closing that sheet has to store the version, which is what makes the row go.+///+/// The seen state is per device and a seeded launch **pins** it to the version+/// now running (Q14), so every other fixture in the suite sees no row at all.+/// This suite is the one that overrides the pin — with+/// `ASTERISM_UI_TEST_LAST_SEEN_VERSION`, naming a version older than the one+/// bundled — and the last case here is the control: the same fixture without+/// the variable shows nothing.+///+/// `seeded-today` is the fixture because the row's conditions are about the+/// screen as much as the library: entries exist, and Today is showing the+/// current day as one day.+final class AnnouncementUITests: XCTestCase {+ let app = XCUIApplication()++ /// The version this build declares (`MARKETING_VERSION`, Q18). A literal,+ /// because the row's title is a literal the reader sees: if the version+ /// moves without this moving, the row this suite drives is not the row the+ /// reader gets.+ private let currentVersion = "0.7.0"+ /// Something older, so the pin leaves the note unseen.+ private let olderVersion = "0.6.0"++ override func setUp() {+ continueAfterFailure = false+ XCUIDevice.shared.orientation = .portrait+ terminateAndWaitForExit(app)+ }++ override func tearDown() {+ terminateAndWaitForExit(app)+ }++ private func launch(+ lastSeenVersion: String?,+ scenario: String = "seeded-today",+ extraArguments: [String] = []+ ) {+ app.launchEnvironment["ASTERISM_UI_TEST_SCENARIO"] = scenario+ app.launchEnvironment["ASTERISM_UI_TEST_RUN_ID"] = UUID().uuidString+ if let lastSeenVersion {+ app.launchEnvironment["ASTERISM_UI_TEST_LAST_SEEN_VERSION"] = lastSeenVersion+ }+ app.launchArguments += extraArguments+ app.launch()+ waitFor(app.collectionViews["recent-list"], "The today fixture opens", timeout: 60)+ }++ private var releaseNoteRow: XCUIElement {+ app.anyElement("today-announcement-release-note")+ }++ private var gettingStartedRow: XCUIElement {+ app.anyElement("today-announcement-getting-started")+ }++ // MARK: - The row, the sheet and the store++ func testTheReleaseNoteRowOpensItsDocumentAndGoesWhenItIsDone() {+ launch(lastSeenVersion: olderVersion)++ let row = waitFor(+ releaseNoteRow, "A version the device has not seen shows its note on Today")+ XCTAssertEqual(+ row.label, "Version \(currentVersion)",+ "The row says exactly what it is, and nothing else")++ row.tap()++ waitFor(app.anyElement("announcement-document"), "The row opens the document")+ XCTAssertFalse(+ app.anyElement("entry-detail-shared").exists,+ "The row is not an entry and does not navigate to one")++ waitFor(app.buttons["announcement-done"], "The sheet offers Done").tap()++ waitUntilGone(+ releaseNoteRow, "Closing the note stores the version, which removes the row")+ waitFor(app.collectionViews["recent-list"], "…and leaves the reader on Today")+ }++ // MARK: - Getting started (Q5, Q20, task 8)++ /// The guide stands **in place of** the settled empty-library message: the+ /// row is there, the message it replaced is not, and the day around it —+ /// the week strip and the releases section — is untouched.+ ///+ /// `seeded-tolerated-emptyWithInvalidSiteTuple` is the fixture for the same+ /// reason `TodayUITests` uses it: one illegal Site tuple and no Entries at+ /// all is the only launch that reaches the empty-library branch.+ ///+ /// Closing this sheet stores nothing, which is the one thing that tells it+ /// from the release note: the row is still there afterwards.+ func testTheGettingStartedRowReplacesTheEmptyMessageAndStoresNothing() {+ launch(lastSeenVersion: nil, scenario: "seeded-tolerated-emptyWithInvalidSiteTuple")++ let row = waitFor(+ gettingStartedRow, "An empty, settled library is shown the guide", timeout: 60)+ XCTAssertEqual(row.label, "Getting started", "The row says exactly what it is")+ XCTAssertFalse(+ app.anyElement("recent-empty").exists,+ "Req: the noted section's message is replaced, not doubled")+ waitFor(app.anyElement("today-week-range"), "…and the day around it is untouched")++ row.tap()+ waitFor(app.anyElement("announcement-document"), "The row opens the guide")+ XCTAssertFalse(+ app.anyElement("entry-detail-shared").exists,+ "The row is not an entry and does not navigate to one")++ waitFor(app.buttons["announcement-done"], "The sheet offers Done").tap()+ XCTAssertTrue(+ waitFor(gettingStartedRow, "Closing the guide stores nothing, so the row stays").exists)+ }++ /// The **guide's** Settings route (Q17): the About section carries it, and+ /// the row pushes the document view rather than presenting it.+ ///+ /// The notes row is the other half of that section and is walked by+ /// `testSettingsOpensTheSameDocument` below, on the fixture whose library+ /// has entries. One row per journey: reaching both in one walk would mean+ /// navigating back out of a pushed document, which proves nothing this+ /// feature owns.+ func testSettingsOpensTheGettingStartedRow() {+ launch(lastSeenVersion: nil, scenario: "seeded-tolerated-emptyWithInvalidSiteTuple")++ waitFor(app.buttons["settings-button"], "Today carries the Settings route").tap()+ waitFor(app.anyElement("settings-view"), "Settings opens")+ scrollUntilTappableAndTap(+ app.buttons["settings-getting-started"], in: app,+ "Settings carries the route to the guide")+ waitFor(app.anyElement("announcement-document"), "The guide, pushed rather than presented")+ }++ // MARK: - The largest Dynamic Type size++ /// Req: the row is **hittable** at `UICTContentSizeCategoryAccessibilityXXXL`+ /// after scrolling to it. At that size the chrome — the search field, the+ /// week strip and any banner — is the list's first screenful, so the row+ /// below it is not in the accessibility tree until the list has scrolled+ /// (Q24 is why it sits after the chrome rather than above it).+ func testTheRowStaysHittableAtLargestDynamicType() {+ launch(+ lastSeenVersion: olderVersion,+ extraArguments: [+ "-UIPreferredContentSizeCategoryName", "UICTContentSizeCategoryAccessibilityXXXL"+ ])++ scrollUntilPresent(+ releaseNoteRow, in: app, "The note's row is reachable at the largest text size")+ // Present is not the same as reachable: the row can be scrolled into+ // the tree and still sit under the navigation bar.+ for _ in 0..<8 where !releaseNoteRow.isHittable {+ app.swipeUp()+ }+ XCTAssertTrue(+ releaseNoteRow.isHittable,+ "Req 3: the row keeps a hit target at the largest Dynamic Type size")+ XCTAssertGreaterThanOrEqual(+ releaseNoteRow.frame.height.rounded(), 44,+ "…and keeps the minimum hit target's height")+ }++ // MARK: - Settings (Q17)++ func testSettingsOpensTheSameDocument() {+ launch(lastSeenVersion: olderVersion)++ waitFor(app.buttons["settings-button"], "Today carries the Settings route").tap()+ waitFor(app.anyElement("settings-view"), "Settings opens")+ scrollUntilTappableAndTap(+ app.buttons["settings-release-notes"], in: app,+ "Settings carries the route to the release notes")++ waitFor(app.anyElement("announcement-document"), "The same document, pushed rather than presented")+ }++ // MARK: - The pin (Q14)++ /// The control for both cases above, and the reason every other suite is+ /// unaffected by this feature: with no variable, a seeded launch starts+ /// having seen the version it is running.+ func testASeededLaunchWithNoOverrideShowsNoRow() {+ launch(lastSeenVersion: nil)++ waitFor(app.anyElement("today-week-range"), "Today is showing one day")+ XCTAssertFalse(+ releaseNoteRow.exists,+ "A device that has already seen this version is shown nothing")+ }+}
diff --git a/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swift b/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swiftindex eaaecd56..2f64835c 100644--- a/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swift+++ b/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swift@@ -124,7 +124,11 @@ final class LibraryDiagnosticsUITests: XCTestCase { /// nothing captured carries the scenario now.) func testEmptyLibraryCarryingADiagnosisStillShowsTheBanner() { launch("emptyWithInvalidSiteTuple")- require(any("recent-empty"), "An empty library still shows its empty state", timeout: 60)+ // `today-announcements` task 8: the Getting started row replaces the+ // settled empty-library message, so it is what an empty library shows.+ require(+ any("today-announcement-getting-started"),+ "An empty library still shows its empty state", timeout: 60) tapDiagnosisBanner() require(app.staticTexts["tuple.test"], "The diagnosed site is named")
diff --git a/Asterism/AsterismUITests/SearchUITests.swift b/Asterism/AsterismUITests/SearchUITests.swiftindex 2c2081a1..f3363687 100644--- a/Asterism/AsterismUITests/SearchUITests.swift+++ b/Asterism/AsterismUITests/SearchUITests.swift@@ -95,7 +95,10 @@ final class SearchUITests: XCTestCase { app.anyElement("recent-search-empty"), "Req 3.4: a query with nothing behind it gets a message, not a blank list") XCTAssertFalse(- app.anyElement("recent-empty").exists,+ // `today-announcements` task 8: the empty-library presentation is+ // the Getting started row now, and a library with entries in it+ // never shows one whatever is typed.+ app.anyElement("today-announcement-getting-started").exists, "The message describes the query, not an empty library") }
diff --git a/Asterism/AsterismUITests/TodayUITests.swift b/Asterism/AsterismUITests/TodayUITests.swiftindex f298802e..04febd09 100644--- a/Asterism/AsterismUITests/TodayUITests.swift+++ b/Asterism/AsterismUITests/TodayUITests.swift@@ -235,8 +235,12 @@ final class TodayUITests: XCTestCase { func testRecentShowsEmptyStateInitially() { launchSeeded()- // Wait for the app to finish loading- let emptyView = app.otherElements["recent-empty"]+ // Wait for the app to finish loading.+ // `today-announcements` task 8: the settled empty-library message is+ // replaced by the Getting started row, so that row **is** the empty+ // state now. `anyElement` rather than `otherElements`, because the row+ // is a button.+ let emptyView = app.anyElement("today-announcement-getting-started") if emptyView.waitForExistence(timeout: 10) { XCTAssertTrue(emptyView.exists, "Expected empty Recent state for a fresh library") }@@ -786,7 +790,9 @@ final class TodayUITests: XCTestCase { func testAnEmptyLibraryKeepsTheStripAndTheReleasesSection() { launch("seeded-tolerated-emptyWithInvalidSiteTuple") - let empty = app.anyElement("recent-empty")+ // `today-announcements` task 8: settled now means the Getting started+ // row, which stands where the message stood; arriving is unchanged.+ let empty = app.anyElement("today-announcement-getting-started") let arriving = app.anyElement("recent-empty-first-sync") let settled = XCTNSPredicateExpectation( predicate: NSPredicate { _, _ in empty.exists || arriving.exists }, object: nil)
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9d9407d8..df943d44 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -161,6 +161,176 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- **Today announcements, phase 2: the getting-started guide and the row+ that replaces the empty-library message+ (`specs/today-announcements/`).** A reader with nothing captured yet+ got one sentence and no explanation of how any of this works. Where+ that settled message stood, Today now draws a `Getting started` row in+ the announcement section, opening a bundled guide that explains+ capturing through the share sheet, teaching a site, and the Today,+ Works and Stats tabs. It shows on a settled empty library with a noted+ section whatever is typed in the search field, takes precedence over a+ release note, stores nothing when its sheet closes, and goes with the+ first capture — no flag records it, because library emptiness already+ says everything a flag would (Q5, Q6, Q20). The arriving state is+ untouched and still shows its own message. Settings' About section+ gains a `Getting started` row above `Release notes`, and is drawn when+ either document reads rather than when the note does, so a build with a+ guide and no note cannot hide it (Q33). macOS shows a Mac variant of+ the guide when one is bundled — the share-menu steps differ — chosen by+ a compile-time `os(macOS)` test, so an iPad gets the shared document.++ The message and the row are now one decision rather than two: Today+ draws the empty-library message only when+ `TodayAnnouncements.drawsEmptyLibraryMessage(branch:announcement:)`+ says so, keying off the same answer the row keys off instead of the+ display branch alone. Keying off the branch would leave a library with+ no readable guide showing neither the row nor the message it replaces —+ a blank screen — and that coupling is now pinned by a unit test rather+ than by a comment.++ The gap phase 1 left open is closed (Q29, Q32). The Today gate checked+ only whether a document existed while Settings checked whether it+ *read*, so a bundled-but-empty guide would have drawn a row rendering+ "This document could not be read" while Settings hid its row. The+ catalog now keeps only documents whose text reads non-empty and is+ built once when the seen state is constructed, which makes both gates+ pure lookups: no `body` evaluation touches the disk, which was the only+ reason to defer it. The previous-versions list inherits the same bar and+ can no longer offer a note that opens on an error. The cost is one read+ per bundled document on the cold-launch path — fine at three, and not a+ pattern to copy without a size check as notes accumulate.++ Four UI assertions moved from the `recent-empty` message to the row,+ `TodayUITests`'s either-settled-or-arriving case keeping its form, and+ new journeys cover the row, the Settings route and hittability at+ `UICTContentSizeCategoryAccessibilityXXXL` after scrolling. The message+ identifier stays in the app, because the message still draws when no+ guide is readable.++ A design-critic pass found the code sound and the *documents* wrong, in+ the same way phase 1's release note had been. Three claims a reader+ would have followed into confusion are corrected: ⇧⌘E exports the work+ or note you have open and is disabled on Stats, not "the notes of the+ list you are looking at"; the re-share sheet saves with the same+ checkmark as a first capture, not an **Update** button, which exists+ only as a constant no view calls; and the guide no longer opens by+ telling a new reader that Asterism "will not be in the share sheet+ until you put it there", an enablement precondition the spec never+ claims — it is behind **More** until favourited. The Mac guide likewise+ now says Asterism does not read the page itself rather than asserting+ macOS forbids it, which the project's own plist comment records as+ unverified.++ The test meant to stop exactly this had a hole: it rejected only+ paragraphs beginning with whitespace, so a bullet hard-wrapped flush+ left produced two one-item lists and a stray paragraph and passed+ green. Counting list markers against list items does not catch it+ either — each marker makes its own list, so the counts never diverge.+ The check is now a source-level tell, a marker line followed by a+ non-blank non-marker line, which is the lazy continuation the subset+ does not have; both wrap styles are proven to fail it and the three+ real documents to pass, by a test that keeps the proof.++ `make test-quick` passes with no failures, no known issues and no new+ compiler warnings — 1,745 tests over 121 suites on the implementing+ run, 1,715 passing marks on an independent one, the two counts being+ the same outcome reported by different formatters, and a control+ warning confirming the log was live. The six failures across the long+ suites are all pre-existing, and the three that phase 1 could only+ argue about are now measured at `main`'s tip — where `main` is one+ Makefile-only commit from the branch point, so the comparison is+ source-identical. Measuring them turned up a fourth pre-existing+ failure nobody had counted. `specs/today-announcements/verification-run.md`+ records the numbers, the attributions and the owner steps.++- **Today announcements, phase 1: a release-note row on Today and an+ About section in Settings (`specs/today-announcements/`).** The app+ could not tell a reader what a new version changed. It now can. A+ bundled Markdown note for the running version draws as a single row at+ the top of Today — its own headerless section directly after the+ chrome rows (Q24), never in the all-days list — shaped like an entry+ row, with the app icon in the cover slot and the title `Version 0.7.0`+ and nothing else. It is not an entry: it stays out of search, the day+ plan, the duplicate plan and every entry count, and leaves the wide+ layout's detail selection alone (Q1). Tapping it opens a sheet through+ `AppNavigation` with a Done button; the sheet stays open when its row+ goes out from under it (Q23). The row shows only while the library has+ entries, Today shows the current day as a single day, a note is+ bundled for the current version, and the stored last-seen version is+ absent or different — downgrades included, because the comparison is+ string inequality (Q10). Closing the sheet stores the version and the+ row goes; opening Release notes from the new About section in Settings+ stores it too, and removes the Today row even on the Mac, where+ Settings is a separate window, because both scenes share one seen-state+ instance (Q22). A read library with no entries stores the version+ silently and shows nothing, so a fresh install and a device joining an+ existing library never meet a note describing a version they did not+ arrive on (Q11). The value is one `UserDefaults` key,+ `announcements.lastSeenVersion`, per device and deliberately not synced+ (Q8, Decision 2); a seeded UI-test launch pins it to the current+ version so no fixture grows a row, and `ASTERISM_UI_TEST_LAST_SEEN_VERSION`+ overrides it for the journeys that want one (Q14).++ Documents are Markdown bundled with the app and drawn with SwiftUI+ views rather than a web view (Decision 1): a pure splitter over a fixed+ subset — `#` to `###`, paragraphs whose unindented lines join with a+ space, one level of unordered and ordered lists, inline bold, italic,+ code and links, and an image alone on its line — with everything+ outside the subset rendered as its own literal text. Images resolve+ from the asset catalog by name, shrink to the text column and never+ enlarge, and a missing asset renders its alt text, which is also the+ accessibility label. Under each note the view lists every other+ bundled version, newest first by numeric comparison of dotted integers+ with a missing component read as zero, so `0.10.0` sorts above `0.9.0`;+ choosing one swaps the note in place. The marketing version moves from+ `1.0` to `0.7.0` in all ten target configurations — the extensions have+ to match the app — and `release-notes-0.7.0.md` is the first bundled+ note (Q18).++ Three implementation resolutions contradicted or went past the written+ approach and are recorded as Q29 to Q31: an announcement whose document+ is absent from the bundle draws no row on Today, not only in Settings;+ the store on close runs from `.onChange` of the presented announcement,+ because `sheet(item:onDismiss:)`'s closure cannot say which item was+ dismissed and only a release note stores; and `announcement-document`+ is a DEBUG-only marker layer rather than an identifier on the document+ view, which would have renamed the previous-versions buttons under it.++ A design-critic pass over the finished phase found the one artifact the+ feature exists to show was itself broken: the note's bullets were+ hard-wrapped with a two-space hanging indent, and the splitter+ deliberately does no lazy continuation, so each bullet came out as a+ one-item list trailed by a stray whitespace-led paragraph. The document+ is unwrapped rather than the subset widened, and the test that should+ have caught it — which only asserted that *some* unordered list existed+ — now pins the block sequence and fails any paragraph beginning with+ whitespace, across every bundled document, so task 8's guide is held to+ the same bar. The same pass moved the seeded-launch pin behind+ `ContentView.launchSeenState()`, since it had been correct only by+ stored-property declaration order and reordering two lines would have+ broken the journeys with no compile error, gave the document gate the+ tests it never had, and stopped the sheet's title bar from still+ reading `Version 0.7.0` after the reader opened an earlier note.++ One gap was left open here and closed in phase 2: the Today gate+ consulted the bundle's file listing while Settings read the text, so a+ bundled-but-empty document still drew a row that rendered "This+ document could not be read" (Q29, Q32).++ The unit bundle is green — `make test-quick` at 1,711 passing with no+ failures and no new compiler warnings on either platform, over two+ independent runs. `make test-ui` was run on the implementation+ branch and carried four failures; one was this feature's own, an+ accessibility journey that asserted a Settings row without scrolling+ after the About section moved the fold, and it is fixed. The other+ three sit on the Works tab's filter menu, a surface this phase does not+ touch. Phase 2 measured them at `main`'s tip rather than leaving them+ argued: all three fail there too, in a worktree holding none of this+ branch's code (`verification-run.md` §2.1). The three announcement+ journeys pass on their own. Getting started and the empty-library rows+ are phase 2.+ - **Catch-up mode: a `Catching up` reading status and a `Catching up` section on Today (`specs/catch-up-mode/`).** A reader behind on a story has no reason to wait for its release day. The reading status control
diff --git a/CLAUDE.md b/CLAUDE.mdindex 720ba6fa..06403b02 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -351,8 +351,38 @@ create or re-mark a store, migrate, reconcile, or `fatalError` on a misconfiguration. It preserves the raw share to the pending-capture queue before it tries to open the library, and deletes that record on commit and on cancel. The queue is a directory of atomically renamed files under the App-Group, not a store and not a log. Cross-launch state of every kind is a marker-file there; the project has zero `UserDefaults` usage.+Group, not a store and not a log.++**Cross-launch state defaults to `UserDefaults`; a marker file is the+exception and needs one of the reasons below.** Per-device state that only the+app reads goes in `UserDefaults` (`@AppStorage` in a view): the works sort+order, the group-by-series toggle, the Mac's restored tab and selections+(`ipad-and-mac-layouts` Q23), a last-seen version. Logic that reads it takes an+injected `UserDefaults` so tests can hand it a throwaway suite, and a seeded+UI-test launch resets the keys it can change: removing them where absence is+the neutral value (`works-list-options` Q8), or **pinning** them where removal+would itself change what the fixture shows (`today-announcements` Q14 — an+absent last-seen version puts a release-note row on every fixture that holds+entries). Use a marker file under the App Group only when the state:++- **is read or written by both the app and the share extension** — standard+ defaults belong to one process and a shared suite is cached per process, so+ one side can read a stale value (the readiness marker, the pending-capture+ queue, `ExportOwed/`);+- **must be checked before any store or container is opened** — the extension+ checks the readiness marker before it constructs a container;+- **needs an atomic, crash-safe write** — a renamed file exists or it does+ not, while defaults are flushed lazily (the import-in-progress sidecar, the+ pending-capture records);+- **describes the library rather than the install, so it has to follow the+ library root** — tests and UI-test launches point the library at a temporary+ root and the markers move with it (the migration sidecar, the sync status).++Earlier decision-log entries that say the project has "zero `UserDefaults`+usage" (`cloudkit-mirroring` Q34, `configurable-work-types`) record a+consistency habit, not a weighed decision; the files they placed still belong+where they are, for the reasons above. Neither store is for library data: that+is SwiftData, and anything two devices must agree on syncs with the library. **Conflicts.** Ordinary field edits converge last-writer-wins per row, and that is accepted for a single-reader library (`site-display-names`,
diff --git a/docs/agent-notes/testing.md b/docs/agent-notes/testing.mdindex 68d2ce58..8705b556 100644--- a/docs/agent-notes/testing.md+++ b/docs/agent-notes/testing.md@@ -1266,6 +1266,26 @@ UI test may have: a suite that reached a site would be asserting that site's markup. The stub is the same arrangement `ASTERISM_UI_TEST_SUGGESTION` and `ASTERISM_UI_TEST_EXTRACTION` use for the model clients. +**Every seeded launch pins `announcements.lastSeenVersion`.**+`ContentView.launchSeenState()` writes the running `MARKETING_VERSION` into the+key before the seen state is built, so no fixture shows a release-note row+(`today-announcements` Q14; removing it instead would put that row on every+fixture holding entries and shift the rows under a large number of existing+journeys). A journey that wants the row sets+`ASTERISM_UI_TEST_LAST_SEEN_VERSION` to an older version. Two consequences+worth knowing before you debug either one:++- There is **no** launch that leaves the key absent — the variable can only set+ a value, never remove one — so the Q11 silent store (a read, empty library+ with nothing stored records the version and shows no note) cannot be+ exercised from a UI journey at all. It is covered at the rule and seen-state+ level only.+- `recent-empty` is no longer what a settled empty library shows.+ `today-announcement-getting-started` is, unless the build bundles no readable+ guide, in which case the message returns. Four assertions moved for this+ (`TodayUITests` twice, `LibraryDiagnosticsUITests`, `SearchUITests`); the+ identifier still exists in the app for the no-guide case.+ ## A decorative view is asserted through `uiTestMarker`, not an identifier A cover slot is decorative for VoiceOver (`work-thumbnails` Req 6.3), so it can
diff --git a/specs/OVERVIEW.md b/specs/OVERVIEW.mdindex 878d96e4..faba7ecb 100644--- a/specs/OVERVIEW.md+++ b/specs/OVERVIEW.md@@ -47,6 +47,7 @@ | [Update Schedule](#update-schedule) | 2026-09-15 | Done — all 30 tasks implemented 2026-09-16; `make test-core` (3,013 tests, zero known issues), `make test-quick`, `make test-ui-ipad` (27/27) green, `make test-performance-m4 RUNS=3` with the ten documented known issues and `todayPublication` at 0.80–0.88 s under a 2 s budget; the owner's device steps in `prerequisites.md` remain | Full spec. A reader-set list of release weekdays on every work under schema V15 with markers `"14"` → `"15"` and the archive at 14/15, set by seven toggles in the editor's Status card and shown on the meta line; the Recent tab becomes **Today**, a week strip over the day's releases and notes with its own typed route stack, inheriting Recent's banners, duplicate sections and search and superseding the 100-row cap; a Works filter finds works with no days. Manual only, no model. | | [Catch-Up Mode](#catch-up-mode) | 2026-09-16 | Done — both phases landed 2026-09-17; four pre-existing UI-test failures recorded in its verification run. Open: the full `make test-performance-m4` has not been run against the fixture with its 66 catch-up works | Smolspec. A fourth reading status, `catchingUp`, for a work the reader is behind on: it shows in a `Catching up` section on Today on the current day and future days whatever its work status or release days, while its release days are parked; no schema bump and no archive generation bump. | | [Share Sheet Character Chips](#share-sheet-character-chips) | 2026-09-18 | In Progress | Smolspec (T-2317). The share sheets' cast text row becomes name-only chips; tapping one opens an inline card with that character's aliases and note, never facts. A cast past two chip rows collapses behind a `+N more` chip (Decision 1). Read-only, no schema change; `FlowLayout` moves into ConstellationKit. Supersedes `share-sheet-characters` Q2 (notes) and Q6 (no pills). |+| [Today Announcements](#today-announcements) | 2026-09-19 | Done — `make test-core` (3,002 checks, zero known issues), `make test-quick` and `make build-mac` green; the six failures across `make test`, `make test-ui` and `make test-ui-ipad` are measured to reproduce at `main`'s tip (`verification-run.md` §2) | Smolspec. A release note and a getting-started guide surface on Today as one row that looks like an entry row and opens a sheet showing a bundled Markdown document, rendered natively with images; both stay reachable from a new About section in Settings. The release-note row shows when the marketing version differs from a per-device last-seen version kept in `UserDefaults` and hides when its sheet closes; getting started replaces the settled empty-library message and goes with the first entry. No schema change; the marketing version becomes 0.7.0. | --- @@ -786,3 +787,16 @@ Smolspec. Both capture sheets draw the work's cast as chips carrying the main na - [tasks.md](share-sheet-character-chips/tasks.md) - [decision_log.md](share-sheet-character-chips/decision_log.md) - [implementation.md](share-sheet-character-chips/implementation.md)++---++## Today Announcements++**Created:** 2026-09-19 · **Status:** Done — smolspec and ten tasks approved 2026-09-20, all ten implemented the same day. Q1–Q33 and Decisions 1–2 in the log; suites and failure attribution in `verification-run.md`.++Smolspec. Two announcements, a release note and a getting-started guide, each drawn on Today as a single row that copies the entry row's look, titled exactly `Version <number>` or `Getting started` with the app icon in the cover slot, in its own headerless section after the chrome rows. Tapping opens a sheet with a Done button that renders a bundled, owner-written Markdown document through a small native renderer over a fixed subset, with images from the asset catalog (Decision 1); Prism's WebKit renderer was investigated and rejected. The release-note row shows while the library has entries and the marketing version differs from a per-device last-seen version kept in `UserDefaults` (Decision 2, which also corrected the `CLAUDE.md` storage rule), hides when its sheet closes, and lists earlier versions under the note. A read library with no entries and nothing stored records the version silently. Getting started replaces the settled empty-library message and goes with the first entry, with no stored flag. Both documents are reachable from a new About section in Settings. No schema, archive or marker-file change; the marketing version becomes 0.7.0.++- [smolspec.md](today-announcements/smolspec.md)+- [tasks.md](today-announcements/tasks.md)+- [decision_log.md](today-announcements/decision_log.md)+- [verification-run.md](today-announcements/verification-run.md)
diff --git a/specs/today-announcements/decision_log.md b/specs/today-announcements/decision_log.mdnew file mode 100644index 00000000..e3ccd075--- /dev/null+++ b/specs/today-announcements/decision_log.md@@ -0,0 +1,119 @@+# Decision Log: Today Announcements++## Quick Decisions++| ID | Date | Decision | Rationale |+|----|------|----------|-----------|+| Q1 | 2026-09-19 | An announcement is its own row value that copies the entry row's look; it is not an entry | Owner decision. A faked entry would carry Teach and Resolve actions and enter search, the day plan and the duplicate plan |+| Q2 | 2026-09-19 | The row sits in its own headerless section at the top of Today, on the current day only, hidden while searching | Owner decision. Under the noted header it would read as something the reader captured |+| Q3 | 2026-09-19 | Row titles are exactly `Getting started` and `Version <number>`, nothing else, with the app icon in the cover slot | Owner decision |+| Q4 | 2026-09-19 | The release-note row hides when its sheet closes, not when it opens | Owner decision. Hiding on open makes an accidental tap permanent before anything was read |+| Q5 | 2026-09-19 | Getting started shows on a settled empty library and replaces the `recent-empty` message; it never shows while a library is arriving; the first entry removes it and no flag is stored | Owner decision. Library state already says everything a flag would, and a second device joining a library is not a first use |+| Q6 | 2026-09-19 | Getting started takes precedence over the release note, and at most one row shows | Owner decision, and the same edge case as Prism's bundled-documents Req 4.8 |+| Q7 | 2026-09-19 | Only the newest note is announced; earlier versions are a generated list at the bottom of the document | Owner decision. Simpler than a "since your version" digest, and Settings reaches the same list |+| Q8 | 2026-09-19 | Seen state is per device and does not sync | Owner decision. Each device updates on its own, and syncing a flag would need a schema bump |+| Q9 | 2026-09-19 | Notes are handwritten Markdown, one file per version, `release-notes-<version>.md`; a version without a file announces nothing | Owner decision. `CHANGELOG.md` is developer-facing. A filename prefix is used because synchronized folder groups flatten resources into the bundle root |+| Q10 | 2026-09-19 | Version change is string inequality against `CFBundleShortVersionString`, so a downgrade counts; ordering of the previous-versions list is numeric per dotted component | Matches Prism's Req 4.7; string ordering would put 1.10 before 1.2 |+| Q11 | 2026-09-19 | With no stored last-seen version: a read library with no entries stores the current version silently, arriving or settled; a library with entries shows the note | A fresh install must not see a note, but every existing install has no stored value when this feature ships, and the owner wants this feature's own note to be the first one shown. Emptiness tells the two apart. Storing only when settled made a joining device's outcome depend on sync timing; storing on any empty read library is deterministic, and a joining device never shows the note that was current when it joined |+| Q12 | 2026-09-19 | One key, `announcements.lastSeenVersion`; Prism's `hasLaunchedBefore` is not ported | Q5 and Q11 make library emptiness the first-launch signal |+| Q13 | 2026-09-19 | The rules and the splitter live in the app target under `ViewModels/` and `Announcements/`, tested by `make test-quick`, not in `AsterismCore` | `ArrivingLibraryPresentation` and `WorksListOptions` set the pattern for presentation logic, and the share extension links `AsterismCore` and has no use for any of this |+| Q14 | 2026-09-19 | A seeded UI-test launch pins last seen to the current version; `ASTERISM_UI_TEST_LAST_SEEN_VERSION` overrides it | Removing the key, as the sort reset does, would put a release-note row on every fixture with content (Q11) and shift rows under existing tests |+| Q15 | 2026-09-19 | Images come from the asset catalog by name; a missing asset renders its alt text | Light, dark and per-platform variants without inventing syntax |+| Q16 | 2026-09-19 | Getting started is one scrolling document with a Mac variant, not a multi-page walkthrough | Shares the renderer and sheet with release notes; the share-sheet steps differ on the Mac |+| Q17 | 2026-09-19 | Settings gets an About section above Backup; opening Release Notes there also stores last seen | Settings has no About section today. Matches Prism's Req 6.6 |+| Q18 | 2026-09-20 | The marketing version becomes 0.7.0 with this feature, and bumping it per release joins the release routine | Owner decision. It is 1.0 in every target, has never moved and has never been pushed to App Store Connect, so lowering it costs nothing. The release-note rule compares strings, so existing installs see the change |+| Q19 | 2026-09-19 | One smolspec covers both announcements | They share the row, section, sheet, renderer and Settings entries; getting started adds one rule and one document |+| Q20 | 2026-09-19 | Getting started shows exactly where the settled message showed: no entries, settled, a day with a noted section, whatever the search query. The current-day and no-search rule in Q2 governs the release note only | Follows from "replaces the message" (Q5). Today's empty-library branch ignores the query by design and draws no noted section on a future day |+| Q21 | 2026-09-19 | No row and no silent store until the library has been read, meaning a snapshot has been published | `AppLibraryModel` reaches `.ready` even when its first refresh failed, with the initial empty presentation still in place. Without the gate a full library could show Getting started and store the version, and that store has no undo |+| Q22 | 2026-09-19 | The silent store runs from `ContentView`; one seen-state instance is created beside the model and shared by every scene; the sheet is presented through `AppNavigation` | The Mac restores its last tab, so Today may not be mounted; Settings is a separate window on the Mac and `UserDefaults` writes do not trigger Observation; two presentations in one turn drop the second, which is why every sheet goes through `AppNavigation` |+| Q23 | 2026-09-19 | The sheet has a Done button and stays open when its row disappears under it | A Mac sheet has no dismiss gesture, and a first capture arriving while Getting started is open must not tear it down |+| Q24 | 2026-09-19 | The row's section sits directly after Today's chrome rows, not above them | At accessibility text sizes the search field, week strip and banners are the list's first section |+| Q25 | 2026-09-19 | The previous-versions list is covered by unit tests only, and no note for an earlier version is bundled | Only one note exists when this ships, so a UI step for the list would never run. An earlier note would describe nothing |+| Q26 | 2026-09-19 | A note file's version must be dotted integers or the file is ignored | Reading a suffix such as `-beta` as zero would make `1.1-beta` collide with `1.0` |+| Q27 | 2026-09-19 | An icon fallback, if needed, is keyed on the bundle's icon name, never a bundle-identifier literal | `make verify-identity` rejects identifier literals in Swift |+| Q28 | 2026-09-19 | A library with works and no entries counts as empty | The owner's rule is phrased in entries, and the message being replaced already treats such a library as empty. Confirmed when the owner approved the spec on 2026-09-20 |+| Q29 | 2026-09-20 | An announcement whose bundled document does not **read as non-empty text** draws no row on Today, not only in Settings | Implementation resolution. The spec states the bar for the Settings rows; a Today row that opens on "could not be read" fails the same way and should not be drawn either. Its consequence was carried into task 8: `emptyLibrarySection` keys off the same `announcement(_:)` answer rather than `plan.branch` alone, or an empty library with no bundled guide would show neither the row nor the message it replaces. Phase 1 applied the bar to *presence in the bundle* only, so a bundled-but-empty document still drew a row where Settings hid one; task 8 closed that by filtering at construction (Q32) once a guide actually shipped and the divergence stopped being theoretical |+| Q30 | 2026-09-20 | The store on sheet close runs from `.onChange` of the presented announcement, not from `sheet(item:onDismiss:)` | Implementation resolution, contradicting the Implementation Approach's wording. `onDismiss`'s closure takes no argument and runs after the binding is nil, so it cannot tell which item was dismissed, and only a release note stores. The alternative was a second `@State` holding the dismissed item: more code, same result. `onChange` covers Done, a swipe-dismiss and a programmatic close, and does not fire when an earlier version is chosen inside the sheet |+| Q31 | 2026-09-20 | `announcement-document` is a DEBUG-only marker layer (`uiTestMarker`), not an accessibility identifier on the document view | Implementation resolution. An identifier on a container renames every descendant, which would have taken the previous-versions buttons' own identifiers. Follows the measured precedent of `coverCandidateSheet` (Q43 of `ipad-and-mac-layouts`). Consequence: like every marker, it does not exist in a `Personal` build |+| Q32 | 2026-09-20 | `BundledAnnouncements.catalog(in:)` keeps only documents whose text reads non-empty, and the catalog is built once in `AnnouncementSeenState.init`; `AnnouncementCatalog(filenames:)` stays pure and unfiltered | Makes Today and Settings apply one bar through one answer, and lets both become pure catalog lookups — no `body` evaluation touches the disk, which was the only reason phase 1 deferred this. The cost is one read per bundled document on the cold-launch path, paid before the first frame. Accepted at three documents. The bound to watch is the **count** of notes, not their size: it is strictly one read per bundled note, unbounded as releases accumulate, all synchronous and all before the first frame. A file-size check is the wrong instrument — still one syscall per note, and it cannot tell nine bytes of whitespace from nine bytes of prose, which would reopen the Q29 hole it is meant to close. The scheme that scales is to read only the documents a row can actually open (the two guides, the note for the current version, the newest note), at most four however many are bundled, with the previous-versions list taking names from the unfiltered listing. Worth doing when the count passes roughly a dozen, not now. The catalog **keeps** the text it reads (Q37), so nothing reads a document twice and no `body` evaluation touches the disk |+| Q33 | 2026-09-20 | Settings' About section is drawn when **either** row has a readable document, and Getting started is listed above Release notes | Gating the section on the release note alone would hide a bundled guide in a build with no note. The order matches the smolspec's own listing and Q6's precedence on Today, so one order is taught in both places |+| Q34 | 2026-09-21 | The sheet's navigation title names the kind of document (`Getting started`, `Release notes`), not the row's `Version <number>` | A reader tapping `Version 0.7.0` lands on a bar reading `Release notes`, which is the accepted cost. The document view can switch to an earlier version under the reader, so a version in the title bar goes stale the moment they use the previous-versions list, and naming the kind makes the Today route and the Settings route title the same document identically. The title is the only thing the two routes would otherwise disagree about |+| Q35 | 2026-09-21 | `announcement-version-<version>` is a seventh identifier beyond the spec's enumerated six | The previous-versions buttons need their own identifiers, and keeping them is precisely what Q31's marker-layer choice exists to protect — a container identifier on the document view would have renamed every one of them. Nothing asserts it yet |+| Q36 | 2026-09-21 | The Q11 silent store is accepted with no end-to-end coverage, tested at the rule and seen-state level only | Q14's pin makes it unreachable from a UI journey: every seeded launch writes the key, and `ASTERISM_UI_TEST_LAST_SEEN_VERSION` can only set a value, never remove one, so no launch leaves the library in the state the rule fires on. Closing it needs a removing sentinel — a test-only path through a launch sequence that already carries the declaration-order hazard `ContentView.launchSeenState()` exists to contain. The cost of the wiring being wrong is one note shown to a device joining an existing library, which is the failure Q11 already calls acceptable in its other direction. Recorded rather than fixed; `docs/agent-notes/testing.md` says the same to whoever writes the next journey |+| Q37 | 2026-09-21 | The catalog retains the text it read at construction, and `AnnouncementSeenState` exposes no `Bundle` | The readability filter (Q32) was already reading every document in full and discarding it, while the document view read the same file again on every `body` evaluation — so one document was read twice and the "no `body` touches the disk" principle was stated but not held. Keeping the text makes the view a lookup, and it removes the `(catalog, bundle)` pair that travelled through three initializers with a comment at each hop warning the two must match: the invariant is now structural rather than prose. Block-splitting stays in `body`, deliberately — it is CPU with no I/O, and moving it behind `.task` would flash the "could not be read" arm on the first frame |+| Q38 | 2026-09-21 | One `AnnouncementCardButton` serves both the Today row and the previous-version cards, with its padding **inside** the button's label | The two spellings of the same card differed only in the icon slot and the identifier, so a later change to the announcement card's look had to be made twice. The originals put the padding on opposite sides of the `Button`: the row outside it, matching `TodayEntryRow`, which does that because it has sibling Teach and Resolve buttons — a constraint the announcement row does not have. Inside is the safe choice, because outside leaves a card with no icon holding a tap area far smaller than the 44 pt card that draws it. Visually identical; the hit target only grows, and the version cards gain a single-line limit and an accessibility label they lacked |++## Decision 1: Render Announcement Markdown With a Small Native Renderer++**Date**: 2026-09-19+**Status**: accepted++### Context++Release notes and the getting-started guide are Markdown with images, so the owner can show how the app works. SwiftUI renders inline Markdown only: `AttributedString(markdown:)` handles bold, italic, code and links, and drops headings, lists and images. The project has no third-party packages. The owner's Markdown reader, Prism (`../prism`), was investigated as a source of reusable rendering code.++### Decision++Split the document into blocks with a small parser of our own over a fixed subset (headings, paragraphs, one-level lists, images on their own line) and draw each block as a native SwiftUI view, using `AttributedString(markdown:)` for inline styling. If the subset becomes a burden, add `swift-markdown` as the parser and keep the native views.++### Rationale++Every document is written by the owner, so the subset can stay strict and the fidelity problems a general renderer solves do not arise. Native views take the app's typography, colours, Dynamic Type and dark mode without a stylesheet. The splitter is a pure function and is unit-testable. A wrong call here is local: replacing the renderer touches one view and one parser, not the rows, the rules or the documents.++### Alternatives Considered++- **Prism's renderer**: parse with `swift-markdown`, emit HTML, serve it to a web view through a custom URL scheme - Rejected: it has no module boundary, extraction is 5,000 to 7,000 lines of Swift plus about 2,500 of CSS and JavaScript, it brings `swift-markdown` and `SwiftSoup`, and most of its size buys fidelity and safety on arbitrary user documents, which these are not+- **The system web view with a Markdown to HTML step**: renders anything - Rejected: needs a stylesheet that imitates the app, a converter, and a web content process in a sheet that otherwise has none+- **A SwiftUI Markdown rendering package**: least code to write - Rejected: the project's first dependency, for a few owner-written pages+- **`swift-markdown` as parser now, native views**: a robust parser maintained by Apple - Not chosen yet: kept as the fallback, because the fixed subset does not need it++### Consequences++**Positive:**+- No dependency and no web view+- Documents match the app's look in both appearances and at every text size+- The parser is small enough to test exhaustively++**Negative:**+- Tables, code blocks, block quotes and nested lists are unavailable to the documents+- A document that strays outside the subset renders as plain paragraphs, which the author only sees by looking++### Impact++`Asterism/Asterism/Announcements/` only.++---++## Decision 2: Keep Seen State in UserDefaults, Not a Marker File++**Date**: 2026-09-19+**Status**: accepted++### Context++The last-seen version must survive launches. The project's habit was a marker file under the App Group, and `CLAUDE.md` said the project had zero `UserDefaults` usage. Tracing that rule found no decision that weighed the two stores: `cloudkit-mirroring` Q34 cites consistency only. The original marker files had real reasons: both the app and the share extension read them, the readiness marker is checked before any store opens, they need atomic crash-safe writes, and they describe the library and so follow its root. The rule was also untrue: five `@AppStorage` keys exist (`works-list-options`, `ipad-and-mac-layouts` Q23).++### Decision++Store the last-seen version in `UserDefaults`, injected into the type that reads it. `CLAUDE.md` now states that cross-launch state defaults to `UserDefaults`, with a marker file only for the four reasons above.++### Rationale++None of the four reasons applies. Only the app reads the value, nothing depends on it before the store opens, a lost write costs one extra row, and it describes the install, not the library, so `Development` and `Personal` should each keep their own, which standard defaults already do. It also lets Prism's state logic and tests port nearly unchanged.++### Alternatives Considered++- **A marker file under the App Group**: consistent with the older files - Rejected: none of the reasons those files exist applies, and it would follow the library root, which is the wrong scope for a per-install value+- **A synced column or table**: one acknowledgement for all devices - Rejected: needs a schema bump, and per-device notes are what the owner wants (Q8)++### Consequences++**Positive:**+- Tests use a throwaway suite, with no temporary directories+- The project rule now says why, so the next case can be decided on its merits++**Negative:**+- Two kinds of cross-launch state exist, and a contributor has to read the rule to pick one+- UI-test launches must manage one more defaults key (Q14)++---
diff --git a/specs/today-announcements/smolspec.md b/specs/today-announcements/smolspec.mdnew file mode 100644index 00000000..9a2edb6d--- /dev/null+++ b/specs/today-announcements/smolspec.md@@ -0,0 +1,57 @@+# Today Announcements++## Overview++The app has no way to tell a reader what a new version changed, and a reader with an empty library gets one sentence and no explanation of how capturing works. This change adds two announcements to the Today screen, a release note and a getting-started guide, each drawn as a row that looks like an entry row and opens a sheet showing a bundled Markdown document. Both documents stay reachable from Settings. Decisions and their reasons are in `decision_log.md`.++Terms: the **noted section** is Today's list of captured entries. An empty library is **arriving** while nothing has reached the device from iCloud yet (`recent-empty-first-sync`) and **settled** once it is known to be empty (`recent-empty`). The **cover slot** is the fixed-size leading area of an entry row that holds a work's cover. The library is **read** once the app has published its first snapshot of it; before that, an empty Today proves nothing.++## Requirements++- The system MUST draw an announcement as a row in its own list section with no header, placed directly after Today's chrome rows (search field, week strip, banners) and before every content section. The row MUST use the entry row's card, padding, minimum height, title font and cover-slot size, show the app icon aspect-fitted and centred in the cover slot, and show a one-line title and nothing else. The title is exactly `Getting started` or exactly `Version <number>`, where the number is the app's marketing version (`CFBundleShortVersionString`).+- An announcement row MUST NOT be an entry: it never appears in search results, the all-days list, the day plan, the duplicate plan or any entry count, carries no Teach or Resolve pill, takes no selection highlight, and leaves the wide layout's detail selection alone.+- The row MUST be one button whose accessibility label is its title, with the icon hidden from accessibility, and MUST be hittable at `UICTContentSizeCategoryAccessibilityXXXL` after scrolling to it.+- The system MUST show at most one announcement row, and none until the library has been read. Getting started takes precedence over the release note.+- Tapping the row MUST open a sheet that renders the announcement's document with a Done button. It MUST NOT navigate to an entry page. A sheet that is open MUST stay open when its row disappears underneath it.+- **Getting started** MUST show exactly where Today draws the settled empty-library message today: the library has no entries, is settled, and the selected day has a noted section (today or a past day), whatever is typed in the search field. It MUST replace that message: the noted section then draws nothing. The arriving state is unchanged and shows no announcement. No stored flag controls it; the first entry removes it.+- **Release note** MUST show only while the library has entries, Today shows the current day as a single day (no search query, no banner filter), a bundled note exists for the current version, and the stored last-seen version is absent or is not the same string as the current version, downgrades included.+- WHEN the library has been read, has no entries and no last-seen version is stored, the system MUST store the current version without showing a release note, whether the library is arriving or settled and whichever screen is showing.+- WHEN a release-note sheet closes, the system MUST store the current version as last seen, which removes the row. Closing the getting-started sheet stores nothing. Opening Release notes from Settings MUST store it too, and MUST remove the Today row even where Settings is a separate window. The value is per device and MUST NOT sync.+- Under every release note the document view MUST list every other bundled version, newest first by numeric comparison of dotted integers with a missing component read as zero. Choosing one MUST replace the shown note without closing the sheet. A version without a bundled note, or a note file whose version is not dotted integers, is never listed and never produces a row.+- Settings MUST gain an About section directly above Backup with `Getting started` and `Release notes` rows that push the same document view. A row MUST be hidden when its document is missing, unreadable or empty. Release notes opens the newest bundled note.+- Documents MUST be Markdown files bundled with the app and drawn with SwiftUI views, not a web view. The supported subset is: `#` to `###` headings, paragraphs (consecutive lines join with a space; a blank line ends a block), unordered lists and ordered lists numbered from 1 (one level), inline bold, italic, code and links, and an image on a line of its own as ``. A block outside the subset (table, code fence, block quote, nested list item, raw HTML) MUST render as a paragraph of its literal text. Inline text that fails to parse MUST render as plain text. A link opens in the system browser.+- An image MUST load from the asset catalog by name, keep its aspect ratio, shrink to the text column's width when wider and never enlarge, and use its alt text as the accessibility label. A missing asset MUST render the alt text in its place.+- On macOS, and not on iPad, getting started MUST show the Mac variant of the document when one is bundled, and the shared document otherwise.+- Rendered documents MUST follow Dynamic Type and the app's light and dark appearance. Identifiers: `today-announcement-getting-started`, `today-announcement-release-note`, `announcement-document` on the document view in both the sheet and Settings, `announcement-done`, `settings-getting-started`, `settings-release-notes`.+- A seeded UI-test launch MUST set the last-seen version to the current version before anything reads it, so no fixture shows a release-note row unless the launch environment names a different last-seen version.+- The marketing version MUST move from `1.0` to `0.7.0` in every build configuration of every target (the extensions' version has to match the app's), with a bundled note for `0.7.0` describing this feature.++## Implementation Approach++- **Pure rules, new file `Asterism/Asterism/ViewModels/TodayAnnouncements.swift`**, shaped like `ArrivingLibraryPresentation.swift` in the same folder (a `nonisolated enum` of static functions): the `TodayAnnouncement` value (`gettingStarted`, `releaseNote(version:)`) with its title; a function from (library has been read, library has no entries, is awaiting first sync, selected day has a noted section, shows one current day, last-seen version, current version, bundled versions) to the row to show; a second function from (read, no entries, last-seen version) to whether to store silently; and the version ordering. "Read" is a published snapshot, the distinction `ArrivingLibraryPresentation.hasContent(snapshotGeneration:)` already draws for Stats: `AppLibraryModel` reaches `.ready` even when its first refresh failed, leaving the initial empty presentation in place. "No entries" is `TodayDisplayPlan.branch == .emptyLibrary` (`Asterism/Asterism/Views/TodayView.swift:930`), the test the settled message uses. "Shows one current day" is `!plan.spansAllDays` with the selected day equal to the current day.+- **Seen state, beside it**: a small `@Observable` type over an injected `UserDefaults` (`.standard` in the app) holding one key, `announcements.lastSeenVersion`, and the bundled versions read once at creation. One instance is created beside `AppLibraryModel`, after the UI-test pin below has been applied, and handed to every scene, so a store made from the Mac's separate Settings window is observed by Today. Port the shape of `BundledDocumentState` from the owner's Prism repository (`/Users/arjen/projects/personal/prism/prism/Models/BundledDocument.swift`, tests in `prismTests/BundledDocumentTests.swift`), dropping its `hasLaunchedBefore` key. `CLAUDE.md` ("Cross-launch state defaults to `UserDefaults`") is the storage rule (Decision 2).+- **Silent store at the root, not in Today**: `ContentView` runs it from `.task(id:)` or `.onChange` keyed by the snapshot generation and the rule's inputs, never from a `body`. The Mac restores its last tab, so Today may not be mounted when the library is first read.+- **Catalog, new file `Asterism/Asterism/Announcements/AnnouncementCatalog.swift`**: a pure function from filenames to documents (`release-notes-<version>.md`, `getting-started.md`, `getting-started-mac.md`) and a thin wrapper that lists a `Bundle`'s `.md` resources. The scheme is a filename prefix because the project's synchronized folder groups copy resources flat into the bundle root; confirm on the first build that the `.md` files are copied.+- **Renderer, `Asterism/Asterism/Announcements/MarkdownBlocks.swift` and `MarkdownDocumentView.swift`**: a pure splitter from a string to blocks (heading, paragraph, list, image) that strips block markers, and a SwiftUI view drawing each block with `AsterismTypography` and `AsterismColors`. Inline styling is `AttributedString(markdown:)` with `.inlineOnlyPreservingWhitespace`, falling back to the plain string when it throws. Images resolve through `UIImage(named:)` / `NSImage(named:)`, which report absence and size where `Image(_:)` cannot. The view owns the previous-versions list and holds the selected version as its own state (Decision 1).+- **Row and sheet, `Asterism/Asterism/Views/TodayAnnouncementRow.swift` and `AnnouncementSheet.swift`**: the row copies `TodayEntryRow`'s layout (`TodayView.swift:1233`: `.constellationCard`, `AsterismLayout.minHitTarget`, `AsterismTypography.serifRowTitle`, the slot size `ThumbnailSlot` draws in `Asterism/Asterism/Thumbnails/ThumbnailSlot.swift`) without taking a `TodayPresentationRow`. The two layouts are separate code; a later change to the entry card has to be made in both. The app icon comes from the bundle's primary icon on iOS (`CFBundleIcons`) and `NSApplication.shared.applicationIconImage` on the Mac, so `Development` and `Personal` each show their own. The sheet wraps the document view in a `NavigationStack` with the Done button; Settings pushes the bare view.+- **Presentation through `AppNavigation`**: the presented announcement is a property on `AppNavigation` and its `.sheet(item:)` sits on `ContentView` with the app's other sheets, keyed by the announcement and never by the version shown inside it. `Asterism/Asterism/Layout/AppNavigation.swift:307-318` documents why two presentations in one turn drop the second. Its `onDismiss` stores last seen only when the dismissed item was a release note.+- **`TodayView.swift`**: a new section in `dayList` (line 376) after `chromeRows` (line 305); `spanningList` never draws it; the settled case of `emptyBranch` (line 569) draws nothing. Today is hosted once for both layouts (`Asterism/Asterism/Layout/AppScreens.swift:57`).+- **`Asterism/Asterism/Views/SettingsView.swift`**: an About section before the Backup section (line 162), using the file's existing `NavigationLink` and `ConstellationSectionHeader` pattern. The release-notes destination stores last seen when it appears.+- **UI-test launch**: `ContentView.launchModel()` (`Asterism/Asterism/ContentView.swift:125-139`) already clears `WorksListStorageKey.seededLaunchResets`; beside it, set the last-seen key in `UserDefaults.standard` to the current version, or to `ASTERISM_UI_TEST_LAST_SEEN_VERSION` when that environment variable is present.+- **Documents**: `Asterism/Asterism/Announcements/Documents/` holds `release-notes-0.7.0.md`, `getting-started.md` and `getting-started-mac.md`. Getting started explains capturing through the share sheet, including adding Asterism to the share sheet's favourites (a manual step the app cannot perform or detect), teaching a site, and the Today, Works and Stats tabs. First drafts are written from the specs for the owner to edit; screenshots are added by the owner later and the documents read correctly without them.+- **Tests**: unit tests in `Asterism/AsterismTests/` for both rule functions (including unread-and-empty: no row, no store), the seen state (throwaway `UserDefaults` suite per test; persistence is proven here, because a seeded launch rewrites the key), the pin's default and override, version ordering, the catalog's filename function, the previous-versions list and the splitter, run by `make test-quick`. UI tests: the four `recent-empty` assertions move to `today-announcement-getting-started` using `anyElement`, since the row is a button (`TodayUITests.swift:239` queries `otherElements` today), and `TodayUITests.swift:789` keeps its either-settled-or-arriving form; `LibraryDiagnosticsUITests.swift:127` and `SearchUITests.swift:98` are the other two. One new journey launches a fixture with entries and an older pinned last-seen version, opens the release-note row, taps Done and sees the row gone; a second opens both Settings rows. `make test-ui-ipad` MUST pass with any `recent-empty` use in its suites moved the same way.+- **Dependencies**: `ArrivingLibraryPresentation`, `TodayDisplayPlan`, `AppNavigation`, `ConstellationKit` card and header modifiers, `AsterismTypography`, `AsterismColors`, `AsterismLayout`.+- **Out of Scope**: the share extension and `AsterismCore`; the schema, the archive and marker files; syncing seen state; notifications or badges; remote or downloadable notes; rendering tables, code blocks, block quotes, nested lists, inline images or raw HTML as anything but literal text; localisation; a multi-page walkthrough; detecting whether the share extension is pinned; a bundled note for any earlier version; a test that fails the build when the current version has no note.++## Risks and Assumptions++- Risk: the bundle's primary icon is not loadable by name on iOS when the icon is an Icon Composer `.icon` file | Mitigation: verify on the simulator first; if it yields nothing, load a rendered image from `Assets.xcassets` named after the bundle's icon name (`CFBundleIconName`, `AppIcon` or `AppIcon-dev`), never after a bundle-identifier literal, which `make verify-identity` rejects in Swift. That path needs the owner to export two images and is the only owner prerequisite this spec can produce.+- Risk: a release-note row on seeded fixtures shifts rows under existing UI tests | Mitigation: the seeded launch pins last seen to the current version; only the new journeys override it.+- Assumption: a device that joins an existing library never shows the note that was current when it joined, because it stores silently while still empty. A new install whose first capture came through the share extension before the app was ever opened shows the current note once. Both accepted.+- Assumption: a library with works and no entries counts as empty, as it does for the message being replaced, so it shows Getting started until its first capture.+- Assumption: a reader whose iCloud state keeps the library arriving sees the arriving message and no Getting started, as today.+- Assumption: every release that should announce itself bumps the marketing version and adds a note file; a release without a note announces nothing, by design.+- Prerequisite: none for the code. Screenshots for the documents are the owner's and are not needed for the feature to work.++## Escalation Note+This change was scoped as a smolspec. If implementation reveals ambiguity only the user can resolve, an irreversible boundary (public API, persisted schema, auth path), or a contested architectural choice, stop and escalate to the full spec workflow rather than deciding it inline.
diff --git a/specs/today-announcements/tasks.md b/specs/today-announcements/tasks.mdnew file mode 100644index 00000000..43bfcee0--- /dev/null+++ b/specs/today-announcements/tasks.md@@ -0,0 +1,75 @@+---+references:+ - specs/today-announcements/smolspec.md+ - specs/today-announcements/decision_log.md+---+# Today Announcements++## Release note++- [x] 1. Announcement rules decide which row shows and when the version is stored silently <!-- id:ar8o6x2 -->+ - smolspec.md Requirements on at-most-one row, Getting started, Release note and the silent store; Implementation Approach 'Pure rules'. New file Asterism/Asterism/ViewModels/TodayAnnouncements.swift holding the TodayAnnouncement value with its exact titles, the row function, the silent-store function and dotted-integer version ordering.+ - Done when unit tests in Asterism/AsterismTests/ cover: no row and no store before the library is read; getting started only on no entries, settled and a day with a noted section, regardless of search; getting started beats the release note; release note only with entries, one current day, a bundled note for the current version and an absent or different stored version, downgrade included; silent store on a read library with no entries and nothing stored, arriving or settled; ordering puts 0.10.0 after 0.9.0 and reads a missing component as zero. make test-quick passes.++- [x] 2. Seen state keeps the last-seen version per device and seeded UI-test launches pin it <!-- id:ar8o6x3 -->+ - smolspec.md Implementation Approach 'Seen state' and 'UI-test launch'; decision_log.md Decision 2, Q12, Q14. One key, announcements.lastSeenVersion, over an injected UserDefaults; port the shape of Prism's BundledDocumentState and its tests without hasLaunchedBefore.+ - ContentView.launchModel() sets the key to the current version on a seeded launch, or to ASTERISM_UI_TEST_LAST_SEEN_VERSION when present, before the seen state is created.+ - Done when unit tests using a throwaway UserDefaults suite per test prove: a stored value survives a new instance; storing updates the observed value; the pin's default yields no release-note row through the task 1 rule; the override yields one. make test-quick passes.+ - Blocked-by: ar8o6x2 (Announcement rules decide which row shows and when the version is stored silently)++- [x] 3. Bundled documents are found by filename and Markdown splits into blocks <!-- id:ar8o6x4 -->+ - smolspec.md Requirements on documents and the supported subset; Implementation Approach 'Catalog' and 'Renderer'; decision_log.md Decision 1, Q9, Q26. Pure code only, no views: AnnouncementCatalog's filename function with its Bundle wrapper, and the MarkdownBlocks splitter.+ - Done when unit tests cover: release-notes-<version>.md, getting-started.md and getting-started-mac.md are recognised and a version that is not dotted integers is ignored; each block kind splits correctly; consecutive lines join with a space and a blank line ends a block; ordered lists number from 1; an image line yields alt text and asset name; a table, code fence, block quote, nested list item and raw HTML each come out as a paragraph of their literal text. make test-quick passes.++- [x] 4. A bundled document renders natively with images and a previous-versions list <!-- id:ar8o6x5 -->+ - smolspec.md Requirements on rendering, images, the previous-versions list and identifiers; Implementation Approach 'Renderer'. MarkdownDocumentView draws blocks with AsterismTypography and AsterismColors, inline styling through AttributedString with inlineOnlyPreservingWhitespace and a plain-text fallback, images through UIImage or NSImage named lookup that shrink to the column and never enlarge, alt text in place of a missing asset and as the accessibility label.+ - Under a release note it lists every other bundled version newest first and swaps the shown note as its own state.+ - Done when unit tests cover the list's contents and order for a given catalog, the view carries the announcement-document identifier, a preview or snapshot of a sample document shows every block kind in light and dark, and make test-quick passes.+ - Blocked-by: ar8o6x4 (Bundled documents are found by filename and Markdown splits into blocks)++- [x] 5. The release-note row shows on Today at version 0.7.0 and opens its sheet <!-- id:ar8o6x6 -->+ - smolspec.md Requirements on the row, the sheet, storing on close and the marketing version; Implementation Approach 'Row and sheet', 'Presentation through AppNavigation', 'Silent store at the root' and 'TodayView.swift'; decision_log.md Q18, Q21 to Q24, Q27. One seen-state instance created beside AppLibraryModel and shared by every scene.+ - The row sits in its own headerless section after chromeRows in dayList and never in spanningList.+ - The sheet is presented from ContentView through AppNavigation, has a Done button, stores last seen only when a release note was dismissed, and stays open if its row goes.+ - The silent store runs from ContentView keyed by the snapshot generation.+ - MARKETING_VERSION becomes 0.7.0 in every build configuration of every target, and Asterism/Asterism/Announcements/Documents/release-notes-0.7.0.md is drafted for the owner to edit.+ - Verify on the simulator that the app icon loads for the cover slot; if it does not, stop and report, because the fallback needs images exported by the owner.+ - Done when make build-ios and make build-mac compile, the .md file is confirmed present in the built bundle, and make test-quick passes.+ - Blocked-by: ar8o6x2 (Announcement rules decide which row shows and when the version is stored silently), ar8o6x3 (Seen state keeps the last-seen version per device and seeded UI-test launches pin it), ar8o6x5 (A bundled document renders natively with images and a previous-versions list)++- [x] 6. Settings has an About section that opens the release notes <!-- id:ar8o6x7 -->+ - smolspec.md Requirements on Settings; Implementation Approach 'SettingsView.swift'; decision_log.md Q17, Q22. An About section directly above Backup with a Release notes row that pushes the document view for the newest bundled note, stores last seen when it appears, and is hidden when no note is bundled.+ - The store must remove the Today row on the Mac, where Settings is a separate window.+ - Identifier settings-release-notes.+ - Done when make test-quick passes and the row is reachable in the simulator.+ - Blocked-by: ar8o6x3 (Seen state keeps the last-seen version per device and seeded UI-test launches pin it), ar8o6x5 (A bundled document renders natively with images and a previous-versions list)++- [x] 7. UI journeys cover the release-note row and the Settings row <!-- id:ar8o6x8 -->+ - smolspec.md Implementation Approach 'Tests'. One journey launches a fixture with entries and ASTERISM_UI_TEST_LAST_SEEN_VERSION set to an older version, finds today-announcement-release-note titled Version 0.7.0, opens it, sees announcement-document, taps announcement-done and sees the row gone.+ - A second opens Settings and the Release notes row.+ - A third asserts a seeded launch without the variable shows no release-note row.+ - Done when make test-ui passes.+ - Blocked-by: ar8o6x6 (The release-note row shows on Today at version 0.7.0 and opens its sheet), ar8o6x7 (Settings has an About section that opens the release notes)++## Getting started++- [x] 8. The getting-started row replaces the settled empty-library message <!-- id:ar8o6x9 -->+ - smolspec.md Requirements on Getting started, the Mac variant and Settings; Implementation Approach 'TodayView.swift' and 'Documents'; decision_log.md Q5, Q16, Q20, Q28. The settled case of emptyBranch draws nothing and the getting-started row shows in its place; the arriving state is unchanged.+ - The emptyBranch change must key off the same answer the row keys off - a non-nil AnnouncementSeenState.announcement - and not off the settled branch alone. That gate drops the row where no getting-started document is bundled, so a branch-only condition would leave such a library showing neither the row nor the message. The smolspec pairs 'Getting started shows' with 'the noted section draws nothing' as one fact.+ - Closing its sheet stores nothing.+ - Settings gains the Getting started row, identifier settings-getting-started, hidden when the document is missing. getting-started.md and getting-started-mac.md are drafted from the specs for the owner to edit: capturing through the share sheet including adding Asterism to the share sheet's favourites, teaching a site, and the Today, Works and Stats tabs.+ - The Mac shows the Mac variant and the iPad does not.+ - Done when unit tests cover the variant choice and an empty library with no bundled guide still drawing the message, make build-mac compiles and make test-quick passes.+ - Blocked-by: ar8o6x6 (The release-note row shows on Today at version 0.7.0 and opens its sheet), ar8o6x7 (Settings has an About section that opens the release notes)++- [x] 9. UI tests that asserted the empty-library message assert the getting-started row <!-- id:ar8o6xa -->+ - smolspec.md Implementation Approach 'Tests'. TodayUITests.swift:239 and :789, LibraryDiagnosticsUITests.swift:127 and SearchUITests.swift:98 move from recent-empty to today-announcement-getting-started using anyElement; :789 keeps its either-settled-or-arriving form; any recent-empty use in the iPad suites moves the same way.+ - Add a check that the row is hittable at UICTContentSizeCategoryAccessibilityXXXL after scrolling to it, and a journey that opens the row and the Settings Getting started row.+ - Done when make test-ui and make test-ui-ipad pass.+ - Blocked-by: ar8o6x9 (The getting-started row replaces the settled empty-library message)++- [x] 10. Every suite passes and the changelog records the feature <!-- id:ar8o6xb -->+ - Run make test-core, make test-quick, make test, make test-ui, make test-ui-ipad and make build-mac, all simulator or host and none touching a device, with no new compiler warnings.+ - Add a CHANGELOG.md entry under Unreleased.+ - Fix what fails; do not skip a suite.+ - Blocked-by: ar8o6x8 (UI journeys cover the release-note row and the Settings row), ar8o6xa (UI tests that asserted the empty-library message assert the getting-started row)
diff --git a/specs/today-announcements/verification-run.md b/specs/today-announcements/verification-run.mdnew file mode 100644index 00000000..059d201b--- /dev/null+++ b/specs/today-announcements/verification-run.md@@ -0,0 +1,114 @@+# Verification Run: Today Announcements++Every run below is simulator or host. No device target was built, installed+or launched at any point in this feature, and `CONFIRM_DEVICE_RUN` was never+set.++## 1. Suites, phase 2 final tree++Run by the phase 2 implementation against the tree at `06943260`, on a host+shared with other work.++| Command | Wall time | Exit | Result |+|---|---|---|---|+| `make test-core` | 2 m 29 s | 0 | 3,002 checks, 0 failures, **0 known issues** |+| `make test-quick` | 1 m 12 s | 0 | 1,720 checks, 0 failures; includes `build-mac` and its embedded `AsterismShareExtensionMac.appex` |+| `make build-mac` | ~4 m | 0 | compiled, never installed or launched |+| `make test` | 1 h 56 m | 2 | 1,896 checks, 5 failures |+| `make test-ui` | 1 h 45 m | 2 | 4 failures |+| `make test-ui-ipad` | 21 m | 2 | 29 executed, 1 failure |++`make test-core` showing **zero** known issues is the bar CLAUDE.md sets; this+feature opened no `withKnownIssue` window and closed none.++Two independent `make test-quick` runs by the reviewing agent against the same+tree measured **1,718 passing marks, 0 failures, 0 compiler warnings**, exit 0.+The count differs from the 1,720 above only in what is being counted (check+lines versus emitted pass marks), not in outcome.++## 2. Failure attribution — measured, not argued++Six distinct cases failed across the three long suites. **None is this+feature's.** Four were established by re-running them alone; the three that had+been argued from the diff twice were finally measured against `main`.++### 2.1 The Works filter-menu cases — measured at `main`'s tip++Measured at `main` = `5461194358431acde0ec4ae31d0bfb47072dd937` in a fresh+detached worktree holding none of the branch's code:++| Case | At `main` | Message at `main` |+|---|---|---|+| `WorksCreatorOptionsUITests.testTheCreatorFilterNarrowsTheListAndExplainsAnEmptyOne` | **FAIL** | `The menu offers Any` |+| `WorksListOptionsUITests.testTheReleaseDaysFilterNarrowsTheListByPresenceAndNamesItself` | **FAIL** | `The menu offers Abandoned` |+| `WorksListOptionsUITests.testTheStatusFiltersNarrowTheListAndNameTheirDimension` | **FAIL** | `The menu offers Finished` |++Both suites at `main`: 9 cases, **4** failures, 502.8 s.++**The baseline is clean.** The branch's merge-base with `main` is `1e30f171`,+and `main`'s tip is exactly one commit ahead of it — `54611943`, which touches+only the `Makefile` (a `DEVICE` alias and a device lookup, nothing the+simulator `DESTINATION` path uses). `main`'s tip is therefore source-identical+to the branch point for all app and test code, so there is no window in which+`main` could carry a fix the branch lacks.++This closes a claim that phase 1 and phase 2 each asserted from the+untouched-files argument alone. That argument was true — `WorksView.swift`,+`WorksListOptions.swift`, `WorksListOptionsUITests.swift`,+`WorksCreatorOptionsUITests.swift` and `UIJourneySupport.swift` are absent from+`git diff main...HEAD --name-only` — but it could not rule out the branch+breaking them indirectly through row counts or launch state. Now it is measured.++Two notes for whoever picks this up:++- **A fourth pre-existing failure surfaced that nobody had listed**:+ `WorksListOptionsUITests.testTheRowGlyphsFollowTheTypeTagAndCostTheRowNoHeight`+ fails at `main` with `Test application did not terminate within 5.0 seconds`.+ It is not this feature's either, and it is not in any earlier tally.+- `testTheReleaseDaysFilterNarrowsTheListByPresenceAndNamesItself` names a+ **different** first offending menu item at `main` (`Abandoned`) than on the+ branch (`Any`). It fails either way, so the verdict holds, but the varying+ item says the assertion walks a menu whose contents differ between runs or+ builds. That variance is the thread to pull, not the branch diff.+ `docs/agent-notes/testing.md` documents this `chooseWorksOption` shape — a+ default `swipeUp` skipping rows of the inline `Picker` menu, reported as a+ missing row.++### 2.2 The cases with an existing recorded baseline++`AccessibilityJourneyUITests.testTheEntryTitleCardsWorkNameOpensTheWorkAtLargestDynamicType`+and `WideLayoutUITests.testTheWorkNameInTheDetailColumnOpensTheWorkOnTheWorksPane`+both reproduce verbatim at `215c843` on `main` per+`specs/catch-up-mode/verification-run.md`. The first also failed when re-run+alone here (29.2 s), so it is not suite interference. This branch does touch+`AccessibilityJourneyUITests.swift`, but only a one-line scroll fix in a+*different* test — see §3.++### 2.3 The flake++`CharacterExtractionUITests.testKeepingAPlaceWritesItIntoThePlacesSection`+failed only in the long `make test` run and passed in `make test-ui` (79.4 s)+and alone (80.9 s). It is an on-device-model place-extraction journey, in the+load-flaky family `docs/agent-notes/testing.md` describes.++## 3. The one failure this feature did cause, and fixed++`AccessibilityJourneyUITests.testSettingsSyncSectionIsReachableAndReportsBothDirections`+asserted `settings-sync-import-line.exists` without scrolling. Adding the About+section moved the fold, exactly as `work-creators` had moved it before — the+hazard is recorded in a comment two lines below the assertion. It now uses+`scrollUntilPresent` and passes (34.5 s).++## 4. Owner steps still outstanding++None of these blocks the feature; all are content, not code.++- **The three bundled documents are drafts written from the specs**, as the+ smolspec anticipated, and are the owner's to rewrite:+ `release-notes-0.7.0.md`, `getting-started.md`, `getting-started-mac.md`.+- **Two instruction paths in the guides have never been walked on real+ hardware** and are the most likely thing to be wrong: the iOS share-sheet+ favourites steps, and the macOS+ `System Settings → General → Login Items & Extensions → Sharing` path.+- **Screenshots**, whenever wanted. A missing asset renders its alt text, so+ every document reads correctly without them.
release-notes-0.7.0.md, getting-started.md and getting-started-mac.md were written from the specs for the owner to rewrite. The release note in particular reads as finished shipping prose with no marker saying otherwise.
The iOS share-sheet favourites steps and the macOS System Settings → General → Login Items & Extensions → Sharing path are written from the general shape of those flows. Three earlier factual errors in these guides (a non-existent Update button, a wrong description of ⇧⌘E, and an unverified claim that Asterism is absent from the share sheet until favourited) were found by review and corrected — these two remain unverified.
A bundle declaring 0.7 with a file named release-notes-0.7.0.md shows nothing at all, because the check is a string contains over the version set. The smolspec scoped out a build-time check, so the release routine has to catch this by hand.