Commit Graph
20 Commits
Author SHA1 Message Date
Kgothatso NgakoandClaude Opus 5.5 34e802ce6f refactor: packages, classes and Res under mobi.giza (fork, Phase 3b)
docs/scripts/giza-rename.sh, run over the moves of Phase 3a:

- com.machankura.bennu.{compose,android,desktop} -> mobi.giza.{...}, in
  package lines, imports, fully qualified references, the manifest, mainClass,
  the Android namespace (one value with applicationId again), the m3Audit
  source path, the six docs/scripts tools, and the source links in docs/;
- Res moves from bennu.composeapp.generated.resources to
  mobi.giza.compose.resources, now pinned with packageOfResClass so a later
  rename of the root project leaves the imports alone;
- BennuDatabase, BennuTheme and the other eleven Bennu identifiers are Giza*.

The script's search is now the same pattern as its sed expressions, so on a
renamed tree it finds nothing and changes nothing.

Checked against the Phase 0 baseline: jvmTest 1643 run (1642 + AppDirJvmTest),
0 failed, 2 skipped; compileDebugKotlinAndroid passes; m3-audit prints the
baseline report line for line. iOS is not compiled on this Linux host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 10:40:27 +02:00
Kgothatso NgakoandClaude Opus 5.5 378bb8c800 docs: the ceremony-creation plan is built, and the notes it touched say so (Phase 9)
shared-key-ceremony.md says where a ceremony starts and how one ends early;
subgroups.md points its Phase 10 here; member-chronicle.md says the chronicle
is built and carries nothing; the batch-signing, skipped-keys and Material
notes mark their document examples as removed; the plan records the ten
places the build chose differently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 17:05:03 +02:00
Kgothatso NgakoandClaude Opus 5.5 b75d4b427f Rebrand Curare to Bennu under com.machankura.bennu
Move the packages to com.machankura.bennu.{compose,android,desktop}, the
Android applicationId to com.machankura.bennu.android and the iOS bundle
id to com.machankura.bennu.ios. The root project, launcher label, iOS
product, desktop window, user-facing strings, client tags and the
Curare* classes all say Bennu now.

Left alone on purpose: the mantra/ derivation tags, the `curated` desktop
data directory, the mantra.press relay and the curare.to references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 13:53:45 +02:00
Kgothatso NgakoandClaude Opus 5 79ff9ee1fc fix(chat): the detail pane's view models are the selected room's, not the first one's
In an expanded window the transcript beside the room list showed the
first room opened and stayed there: pick another room and the list
moved on while the pane did not. HomeScreen wraps the pane in
key(chatRoomId), which rebuilds the composition when the selection
changes, but viewModel() does not read composition keys. It scopes to
the nearest ViewModelStoreOwner, and in the pane that is the home
destination's one back stack entry for every room, so the second room's
viewModel(factory = ...) got the first room's ChatRoomMessagingViewModel
and ChatMessageListViewModel back with its factory ignored. A phone never
showed it because a pushed room is its own entry with its own store.

The pane now provides LocalViewModelStoreOwner with
rememberViewModelStoreOwner() under the room key: a store per room,
cleared when the selection moves on, and parked in the home entry's
store so that it survives a rotation. Keying the two viewModel() calls
on the room would have unstuck the pane too, at the price of keeping
every room ever opened -- four DB collectors each -- in the home entry's
store for as long as the home screen lives.

ChatPaneSelectionJvmTest opens two rooms and comes back to the first,
told apart by what was said in them since a name is on the row as well
as the bar; its third case checks the room left behind stops collecting,
which is the case the keyed alternative fails. The conformance doc's
account of the hand-built pair records the trap.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 20:10:13 +02:00
Kgothatso NgakoandClaude Opus 5 ca6c16beb0 refactor(ui): one extended FAB for every screen's primary action, with a gap in it
Twenty screens end their bottom bar in an `ExtendedFloatingActionButton` --
twenty-one buttons, one screen having two -- and eighteen of those were built
from the content-lambda overload with an `Icon` directly followed by a `Text`.
That overload puts nothing between the two, so the icon touched the label on
every one of them: visible in any render, and unnoticed because every FAB in
the app looked the same. Thirteen of the eighteen also carried the same
twenty-line block for looking disabled, because M3 gives a FAB no `enabled`.

**`ExtendedFab`, once, in widgets/buttons.** A label, an icon slot, `enabled`
and `onClick`. It draws `space150` between icon and label, which is the 12dp
M3 names `ExtendedFabEndIconPadding`; it borrows the disabled colours every
other button in the app uses, marks the node disabled so a screen reader does
not announce a button it is happy to press, and drops the press -- so the
thirteen call sites lose their `if (!canX) return@…` guards along with the
block and the `buttonColors` each of them declared. An icon slot rather than
an image, because two screens put a progress indicator where the icon was
while the action they started is out, and they still do.

**Not M3's `text`/`icon` overload, which would have spaced them for free.**
Its source wraps the label in `clearAndSetSemantics {}`: the label leaves the
merged semantics tree, a screen reader is told only what the icon says, and a
test cannot find the button by what it says -- five screen tests do. The
three FABs that were on that overload move to the widget too, and two of them,
Home's "New chat" and "Start the key ceremony", had a decorative icon beside
the cleared label and so no accessible name at all until now.
`ReadOnlyEntrancesJvmTest` had gone to the unmerged tree to find "New chat"
for this reason; the habit is harmless and stays. Every icon's description is
as it was, since several tests reach their FAB by it.

`ExtendedFabJvmTest` pins the decision: found by its label in the merged tree,
the icon before the label with a gap between, and disabled both announced and
refusing the press. The two docs that recorded the old state -- the
conformance account's "left alone" and the npub plan's unmerged-tree note --
each say what superseded them.

Verified with :composeApp:m3Audit (all budgets met, 0 dp literals in spacing
positions), :composeApp:compileDebugKotlinAndroid and :composeApp:jvmTest
(1088 tests, 3 new).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-13 13:31:47 +02:00
Kgothatso NgakoandClaude Opus 5 e6aee79282 refactor: rebrand curated to curare, and the one name that stays on disk
`com.it.curated.{compose,android,desktop}` becomes `to.curare.{compose,android,desktop}`
across 700 file moves, and the app is Curare everywhere a user can read it. This is the
third rename this tree has been through, so the question was never how to spell the new
name but which of the 5074 occurrences of the old one were the brand. `3bc8be53` and
`d26cf6c7` had already sorted most of that, which is why this rename is mechanical where
those two were not -- and why the interesting part is the one place it is still not.

**`APP_DIR_NAME` keeps the old brand, and is the only thing that does.** It names the
desktop app's data directory -- `~/.local/share/curated`, `Application Support/curated`,
`%LOCALAPPDATA%\curated` -- and that single directory holds the Room database, the marmot
group state and the phoenix wallet. Renaming it does not move an install: it silently
starts an empty one beside it and leaves the old chat history and the old seed sitting
where nothing reads them any more. That is the same class of silent failure as the
`mantra/` hash prefixes, so it gets the same treatment -- it stays, with a comment saying
what renaming it would cost and that doing it properly is a first-run migration rather
than a rebrand. The desktop app is `curated` on disk and `Curare` everywhere a user can
read.

**The applicationId and the namespace are one value again, at `to.curare.android`.**
`3bc8be53` split them precisely so `com.it.curated` could land verbatim as the store
identity while the namespace kept `.android`; the decision here was to collapse them, so
both read `to.curare.android` and the manifest's relative `android:name=".CurareApplication"`
and `BuildConfig` resolve against the same package they always did. Debug is
`to.curare.android.debug` through the existing suffix. Worth stating plainly because
nothing in the build will: an applicationId *is* the app's identity to Play, so this is a
new listing rather than an update, and no installed Curated can update into it.

**`CuratedDatabase` -> `CurareDatabase` moves a directory, never a table.** The `@Database`
class name picks the schema *directory*, so
`composeApp/schemas/com.it.curated.compose.database.CuratedDatabase/` becomes
`to.curare.compose.database.CurareDatabase/` and its 19 files move unmodified. What makes
that safe has not changed since last time: the 12 entity classes are still `Mantra*` and
still declare no `tableName`, so Room still takes their class names as the SQLite table
names -- and this rename does not touch one of them. The check is that Room found all 19
schemas at the new directory and generated no twentieth.

**The generated resources package moved because `rootProject.name` did, again.** Compose
Resources derives it from the root project, so `Curated` -> `Curare` silently turns
`curated.composeapp.generated.resources` into `curare.composeapp.generated.resources` and
breaks 72 files' imports at once. Rewritten with them: the two string keys that carried
the brand -- `curated` and `sign_in_is_not_yet_available_while_curated_is` -- their three
call sites, and the eight `docs/scripts/` tools that hardcode the UI source path. The
audit reporting 582 `stringResource` sites and 178 `Icon(` call sites is the evidence
those tools still see the whole tree rather than an empty directory.

**A global rename edits the sentences that describe the previous rename, and two of them
came out false.** `material-design-conformance.md` recorded that `TorchTheme` became
`CuratedTheme` and that `UserAgent` was moved off Torch "when the app was rebranded to
Curated" -- which a blanket sweep turns into a claim about a change that had not happened
when it was written. Same in `HomeScreen`, where "the brand before that one" meant Torch
while Curated was current, and quietly came to mean Curated while still naming
`TorchTheme`. Both now say what happened, in order. The three deliberate Torch records --
the finding at :278, that note, and `NavigationRoutingTest`'s fixture -- are intact.

**What was protected stays protected, and now says "two rebrands".** `TWEAK_TAG`,
`HOST_KEY_DERIVATION_TAG` and `wss://ephemeral.mantra.press` are byte-identical; only the
prose around them moved, because "survived the rebrand to Curated" had stopped being the
whole story. The tree's 1668 `Mantra` and 17 `Torch` tokens differ from the 1666 and 16
before this change only by the words those comments added.

**iOS is `Curare` / `to.curare.ios`**, with the three pbxproj product references renamed
to match, and is unverified here for the same reason as last time -- the build gates the
ios targets behind `isMacOsX` and this was built on linux. The bundle id takes a platform
segment rather than the bare base it translates from, so that it reads alongside an
android applicationId that now carries one: `to.curare.android` and `to.curare.ios`, and
`to.curare` left as the base neither store claims.

1226 tests pass -- 787 in `:composeApp:jvmTest`, 439 in `:composeApp:testDebugUnitTest` --
`:composeApp:compileDebugKotlinAndroid` is clean, and `m3Audit` meets every budget.

Three stale things are left alone, because none of them is branding.
`.gitea/workflows/material-design-conformance.yml` still triggers on `branches: [mantra]`,
which stopped naming a branch that exists somewhere before this change and is now two
brands out; the three `torch_*` string keys still carry a brand two renames old, though
every value they hold reads Curare; and `androidMain/res/values/strings.xml` has opened
`<resources>a` since well before this. Each wants its own change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 13:33:47 +02:00
Kgothatso NgakoandClaude Opus 5 d26cf6c733 refactor: retire the brand before mantra, and keep the three records of it
`3bc8be53` renamed Mantra to Curated by searching for "Mantra", which is exactly why
it missed this: the tree carried a second, older brand -- Torch, from the rename before
that one -- in 130 references and two error messages. A user could still be told to go
and install a product that does not exist.

**`UserAgent` was the last thing publishing the old name, and the reason it could move
is the reason the `mantra/` tags could not.** Both were described the same way -- "it
goes on the wire" -- and that phrase hid two different facts. `CLIENT_NAME` has one
caller: it is the `client` tag on a published NIP-65 relay list, which is public
attribution and nothing else. It is not an input to a hash, so changing it cannot
re-derive a key, cannot orphan a room, and cannot make two clients disagree about a
threshold key; the worst it does is label future relay lists correctly. `TWEAK_TAG` and
`HOST_KEY_DERIVATION_TAG` are hashed, which is the whole difference, and they stay.
`APP_NAME` moved with it and has no callers at all -- dead, and left that way, because
deleting it is not this change.

**`TorchTheme` is `CuratedTheme`, at 130 references across 70 files.** It is the root
theme composable, so the rename reaches every screen, every `@Preview` body, the desktop
entry point and six jvmTest files that compose against it, plus 13 mentions in
`docs/material-design-conformance.md` that document it as a live API rather than as
history. Wide, but mechanical: it is one identifier with no string, table, path or hash
depending on its spelling, which is what makes it the opposite of the 12 Room entities
that kept theirs.

**Two error strings named the wrong product to a user.** "tell <name> to use Torch" and
"they may not have finished setting up Torch" both now say Curated, along with the
commented-out preview fixture beside the first, so the two cannot drift apart if it is
ever uncommented. They stay inline literals rather than moving to the catalogue: both are
set inside a `viewModelScope.launch`, where `stringResource` is not available, and of the
44 view models the five that reach `Res.string` all do it from `@Composable` functions
that merely live in view model files. Nothing here reaches the catalogue from view model
logic, so externalising these would introduce a `getString` pattern the tree does not
have -- worth doing, and worth doing as its own change rather than inside a brand fix.

**The rename caught its own prose, twice.** A comment in `HomeScreen` and a paragraph in
`material-design-conformance.md` each said "`TorchTheme` and two error strings still carry
the older brand" -- true when written, and turned by this very sed into "`CuratedTheme`
... carries the older brand", which contradicts itself. Both now state what is true. It is
worth noting because a global identifier rename edits the sentences that describe the
rename, and those are the ones nothing compiles or tests.

**Three references to "Torch" survive, and rewriting them would destroy information.**
`material-design-conformance.md:278` is the finding that the app once had three names for
one product; the note at :654 is the deferral this change carries out, so it has to say
what was deferred; and `NavigationRoutingTest`'s `"Introducing... Torch"` is documented as
"the screen the bug left people on" -- a test-only fixture no production path emits, whose
value is that it names the state the regression was about. No live code answers to Torch
or to Mantra any more; what is left of both is the record of what was.

1136 tests pass -- 733 in `:composeApp:jvmTest`, 403 in `:composeApp:testDebugUnitTest` --
`:composeApp:compileDebugKotlinAndroid` is clean, and `m3Audit` meets every budget.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 01:02:21 +02:00
Kgothatso NgakoandClaude Opus 5 3bc8be535a refactor: rebrand mantra to curated, and the five names that stay
`press.mantra.{compose,android,desktop}` becomes `com.it.curated.{compose,android,desktop}`
across 680 file moves, and the app is Curated everywhere a user can see it. The work
that mattered was not the rename; it was deciding which of the 6355 occurrences of
"mantra" were the brand and which were something else wearing it.

**"Mantra" was two words in one tree, and only one of them is a brand.** 1369 of the
tokens belong to a domain model -- `MantraArtifact`, `MantraChapter`, `MantraChunk`,
`MantraDialect`, the seven `MantraTranslation*` types, their 15 DAOs and
`MantraRepository` -- and those 12 entity classes declare no `tableName`, so Room takes
the class name as the SQLite table name. A blanket `s/Mantra/Curated/` renames 12 live
tables, which is not a rename but a v20 with 12 `@RenameTable` specs and a regenerated
schema. Asked, the decision was brand surface only, so the domain keeps its name and the
database keeps every one of its tables. The count is the check: the same 1369 tokens are
present before and after, and Room found all 19 existing schemas at the moved directory
and generated no stray -- which is what proves no table moved.

**Renamed instead is the set of names that only ever meant "this app".** `CuratedApp`,
`CuratedApplication`, `CuratedGlobal`, `CuratedNavHost`, `CuratedNavigationSuite`,
`CuratedShapes`, `CuratedConverters`, `defaultCuratedDir`, and `CuratedDatabase` with its
constructor and test. `CuratedDatabase` is safe to rename precisely because the entity
classes were not: the `@Database` class name picks the schema *directory*
(`composeApp/schemas/com.it.curated.compose.database.CuratedDatabase/`), never a table,
so the 19 schema files move unmodified and the AutoMigration chain from 1 is untouched.

**`com.it.curated` is the applicationId; the namespace is `com.it.curated.android`.**
These were one value before, and splitting them is what lets the identifier land verbatim
as the app's store identity while `BuildConfig` and the manifest's relative
`android:name=".CuratedApplication"` keep resolving against the android source package.
The debug build is `com.it.curated.debug` via the existing suffix.

**The generated resources package moved because `rootProject.name` did.** Compose
Resources derives it from the root project, so `Mantra` -> `Curated` silently turns
`mantra.composeapp.generated.resources` into `curated.composeapp.generated.resources` and
breaks all 501 imports at once. They are rewritten, along with the two string keys that
carried the brand -- `mantra` -> `curated` and `sign_in_is_not_yet_available_while_mantra_is`
-- and their three call sites. The seven `docs/scripts/` tools and `m3-audit.sh` hardcode
the UI source path, so they moved too; the audit passing is the evidence they still see
the whole tree rather than an empty one.

**Two hash inputs and a hostname keep the old name, and now say why.**
`SharedKeyDerivation.TWEAK_TAG` and `ChillDkgRitualManager.HOST_KEY_DERIVATION_TAG` are
`"mantra/..."` strings that are fed to SHA256. Renaming them derives different keys from
the same seed: every room already created is orphaned, every completed ChillDKG becomes
unrecoverable, and a Curated client and a Mantra client sharing a group derive different
keys from one threshold key, so their partial signatures aggregate to something that
verifies against nothing. That is a protocol fork and belongs in a `v2` tag, not in a
rebrand. `Relays.ephemeral` stays on `wss://ephemeral.mantra.press` for the duller reason
that it is a relay that is running and is in the bootstrap, publish, finder and DM sets;
pointing it at a name nobody has stood up takes the app off the network. All three sites,
and `docs/shared-key-derivation.md`, now carry the reasoning, because the failure mode of
each is silent and the next reader will otherwise finish the job.

**iOS had never been moved off the brand before this one.** `Config.xcconfig` still read
`PRODUCT_NAME=Torch` with a bundle id of `ac.aux.compose.Aux` -- two brands ago -- so a
Curated repo built a Torch.app. It is now `Curated` / `com.it.curated`, with the pbxproj's
three product references renamed to match. This is wider than Mantra -> Curated and is
called out for that reason; it is also unverified here, because the build gates the ios
targets behind `isMacOsX` and this was built on linux. In the same spirit the last stale
`press.auxiliary.compose` file -- a KMP template test asserting `1 + 2 == 3` -- was
relocated rather than deleted, so the source tree has one root package instead of an
orphan under the vacated one.

**Three things still say the old names on purpose and are not oversights.**
`UserAgent.APP_NAME` and `CLIENT_NAME` still read `"Torch"`, which a previous rename left
deliberately: it goes on the wire to relay operators and is a network identity rather
than a content one. `.gitea/workflows/material-design-conformance.yml` triggers on
`branches: [mantra]` because that is still the branch's real name. And
`docs/material-design-conformance.md:278` records that the top bar once read `"Torch"`
while the window title read `"Mantra"` -- a finding about a past defect, which rewriting
would falsify.

1136 tests pass -- 733 in `:composeApp:jvmTest`, 403 in `:composeApp:testDebugUnitTest` --
`:composeApp:compileDebugKotlinAndroid` is clean, and `m3Audit` meets every budget.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 00:53:05 +02:00
Kgothatso NgakoandClaude Opus 5 a56295b0e2 docs: record what phase 8 built, and what is left for a person across all nine
The plan's last phase becomes a record, and the document gains a closing status:
every count the audit was written to move, from the state in "Where this app
stands" to what `m3-audit.sh` reports today, and a gathered list of what a person
still has to look at — the eight screens with competing filled buttons, the two
list-detail families the pane work did not reach, the container transform, desktop
keyboard traversal, and the avatar picker's selected state.

**The audit caught the previous commit.** `ThemeGallery` added eight string
literals in composables, taking the count 39 -> 47, which is exactly the drift the
budget exists to notice. They are sample text — the words are chosen to be words,
so that colour pairings can be looked at — and putting them in the catalogue would
add eight entries no screen shows and a translator would have to be told to
ignore.

So the audit grows a third exemption marker beside `m3-color-exempt` and
`m3-spacing-exempt`: `m3-string-exempt`, per file rather than per line, because
the exemption is a property of what the file is for and eight markers down one
gallery would say less than one at the top of it. Back to 39, and the report now
says how many files are exempt so the mechanism cannot be used quietly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 08:26:56 +02:00
Kgothatso NgakoandClaude Opus 5 b6aa2111ac docs: record what phase 7 built, including the API the plan named that does not exist
Phase 7 becomes a record. Three things in it are corrections to the plan rather
than notes on it, and all three are the kind that only surface once somebody
tries:

- `MotionSchemeKeyTokens`, which the plan says every spec should come from, is
  `internal` to material3 and not addressable from an app. `MaterialTheme.motionScheme`
  is the public surface and gives the same six specs.
- "every state change in the app is a hard cut" was true of screen states and not
  of navigation, whose default is a 700ms fade in navigation-compose's internals.
  Still worth replacing -- three times M3's duration, and a literal in a
  dependency -- but for a different reason than the one written down.
- Android has no reduce-motion setting. It has "Remove animations", which zeroes
  the animation duration scales, and Compose ignores those scales entirely.

Also what was deliberately left: the container transform between a list item and
its detail screen. It is `SharedTransitionLayout` work, and above the expanded
breakpoint the detail is already beside the list, so there is no container to
transform -- doing it before the pane split settles means writing it twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 08:16:46 +02:00
Kgothatso NgakoandClaude Opus 5 16775bf6c7 docs: record what phase 6 built, and give the audit a floor to defend it
The plan's phase 6 becomes a record rather than a proposal, in the shape the
earlier phases took: what was built, what was decided and why, what a person
still has to look at. Two decisions in it were the product owner's rather than
the code's -- promoting search and profile to navigation destinations, and doing
chat alone rather than all three list-detail families -- and both are named as
such with the date.

**The audit learns two things.**

It counted `NavigationBar(`, `NavigationRail(` and friends, and reported **zero**
for an app that had just grown a navigation bar: `NavigationSuiteScaffold` is
what chooses between them per breakpoint, and the concrete component never
appears in the source. It now counts the scaffold and its items.

And it grew a `floor()` beside `report()`. Every other budget in the file is a
ceiling that ratchets down as a phase lands, which is the right shape for
literals, hardcoded colours and untriaged nulls -- things a careless edit *adds*.
The adaptive work is the opposite: a screen that stops reading the breakpoint
still compiles and still renders, and the count goes down. So `--check` now also
fails when the adaptive API count drops below 12 or the navigation component
count below 2.

**Two `contentDescription = null` that the audit caught in this phase's own
work** -- the navigation item's icon and the new-chat button's -- now say
`Decorative`. Same null, and the same convention phase 3 established: recording
that somebody looked is the whole point, and a budget of zero only holds if new
code obeys it too.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 08:04:00 +02:00
Kgothatso NgakoandClaude Opus 5 043d725599 feat: draw the expressive loading indicator, and stop shouting the sign-out button
Phase 5, second step, of docs/material-design-conformance.md. Two smaller pieces, and a
correction to the plan.

**41 loading states stopped being a gold spinner.** `LoadingDataIndicator` wraps every wait
in the app, and it drew a `CircularProgressIndicator` hardcoded to 80dp in
`colorScheme.secondary` -- the brand gold, which reads as a warning rather than as a wait,
on a component that has a size of its own. It now draws `LoadingIndicator`, which is M3's
component for an indeterminate wait with no progress to report and the one
`MaterialExpressiveTheme` expects to be paired with. One wrapper changed; 41 call sites
follow.

**The profile screen had two maximum-emphasis buttons, and one of them was Sign out.**
Seven actions in one list: five `TextButton`s (edit profile, key packages, change account,
profile keys, network relays) and two filled `Button`s. A filled button is M3's highest
emphasis and is meant for one action per screen, so this was two competing primaries -- and
the more prominent of the pair was the list's most destructive item.

Sharing is now `FilledTonalButton`: it is the useful action, at medium emphasis rather than
maximum. Signing out is a `TextButton` in the error colour, which is not a new pattern --
it is how leaving and deleting a group are already treated in `ChatRoomDetailScreen`.
Screenshot verified on emulator-5554: one tonal button, one red text button, five plain
ones, and a hierarchy a reader can follow.

**The plan was wrong about disabled FABs, and the code was right.** It said five screens
should stop hand-computing a container colour from a `can…` flag and pass `enabled`
instead. **No `FloatingActionButton` overload in material3 1.10 takes `enabled`** -- checked
in the source, zero matches for `enabled: Boolean` in FloatingActionButton.kt -- because
the spec's own position is that an unavailable FAB should not appear at all. Hand-computing
is the only way to show a disabled one.

More to the point, the existing code is already better than the plan assumed: it pairs the
colour with `Modifier.semantics { disabled() }` and a comment saying "looking unavailable
is not being unavailable: without this a screen reader still announces a button it is happy
to press." Left alone, and the plan corrected.

**Eight screens are left for a person.** LandingScreen puts "Sign in" beside "Create
profile", SocialPreconditionScreen puts "Invite a friend" beside "View invites", and six
others do the same. Both members of each pair are filled buttons. Which one is primary is a
product decision about what the screen is *for*, and picking wrong quietly weights a choice
the user is supposed to make freely -- so this is listed in the plan rather than guessed at
here.

**Tests.** 949 pass, 600 jvm over 73 classes and 349 android over 44, unchanged. Both
changes are composition-time rendering, which this repo has no UI test infrastructure to
assert; the device screenshot stands in for it. `:composeApp:compileDebugKotlinAndroid`
builds and the apk runs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 02:01:39 +02:00
Kgothatso NgakoandClaude Opus 5 2117e22d48 refactor: make the 40 interpolated UI strings format strings, and assert the argument order
Phase 4, third step, of docs/material-design-conformance.md. `Text("Add chapter to
${uiState.artifact.name}")` becomes a resource holding `Add chapter to %1$s` and a call
passing the expression. 49 call sites. Literals in composables go 76 -> 39;
`stringResource` goes 374 -> 424.

**A silent bug in the previous commit's extractor, found by this one.** Imports were
tested with `statement in source`, and the generated accessors are named after their
strings -- so `import mantra.composeapp.generated.resources.translate` is a *prefix* of
`...resources.translate_into_which_dialect`. The substring test decided the import was
already there, and the compiler reported "Unresolved reference 'translate'" in a file
whose imports looked complete. Both extractors now match whole lines, and the helper
carries the explanation.

**Four filters, each earned by something the dry run got wrong.**

*A template that is only interpolation has nothing to translate.* `Text("$name")` would
have become a resource holding `%1$s` -- longer, slower, and no more localisable than the
code it replaced.

*A leading or trailing space means it is being glued to a neighbour.* " \\u00b7 %1$s" is a
separator. The test has to be on the format string rather than on the literal halves: a
template opening with an interpolation leaves the first part empty and the second starting
with the separating space, which makes "%1$s Key packages" look like a fragment when it is
a whole label.

*`\\uXXXX` and `\\"` are Kotlin syntax, not XML.* Left alone they would have shipped as the
six visible characters of the escape. They are decoded into the resource, which is UTF-8
and can hold `·` directly. `\\n` is **not** decoded, because
StringCatalogueJvmTest shows Compose Resources processes that one and a real newline in an
XML value would be reflowed by the parser.

*A term of a `+` concatenation is still not a string.* Same rule as the plain extractor.

**Three copy problems surfaced only here, because interpolated strings had never been
checked.** `m3-title-case.py` excludes anything containing `$` -- an interpolation is not a
literal -- so `"$count Key Packages"` had been invisible to every pass so far, as had
`"replying To ${…}"`. And a third instance of the old product name, in
`"...once they're on Torch."`. All three fixed. Worth noting as a gap in the checker rather
than a one-off: title case inside a template is still unchecked, and there are 83
concatenation fragments left where it could hide.

**Two new assertions, on the two things a compiler cannot see.** Argument *order* is
decided by where each `${…}` sat, and a transposition compiles and reads plausibly --
"Recovered 3 of 12" against "Recovered 12 of 3" -- so a two-argument and a three-argument
string are asserted end to end. The three-argument one doubles as the check that `·`
was decoded rather than passed through.

**What is deliberately left.** 83 literals that are terms of a `+` concatenation.
Reassembling `"a " + x + " b"` into one format string means deciding what the whole
sentence is, and several are pluralisations -- `(if (n == 2) "event" else "events")` --
which want a real plural resource rather than a format argument, and that is an API choice
rather than a rewrite. `m3-extract-formatted.py --remaining` lists them.

**Tests.** 949 pass, 600 jvm over 73 classes and 349 android over 44, up from 947/598/349.
`:composeApp:compileDebugKotlinAndroid` builds; the debug apk installs and runs on
emulator-5554 through onboarding, the message list and a chat room with its text intact.
`m3-audit.sh --check` exits 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 01:45:35 +02:00
Kgothatso NgakoandClaude Opus 5 1f24aaf4bb fix: give the two single-field screens their initial focus, and check 200% text on a device
Phase 3, final step, of docs/material-design-conformance.md. The tree had **zero** uses of
`FocusRequester`, `LocalFocusManager` or `focusProperties`, so no screen defined where
keyboard focus starts.

**Two places get it, and only two.** M3's flow guidance asks for an initial focus per
screen and, for a dialog, that "focus is set to the dialog component, likely to a specific
interactive element within the dialog such as a text input field":

  - `StartDirectMessageToNpubOrNip05Dialog` -- one field and two buttons. Without this the
    dialog opens with nothing focused, so a keyboard or switch user tabs in from wherever
    focus happened to be.
  - The desktop `PassphraseGate` -- the first screen of the desktop app, whose entire
    content is one field, and where there is no tap to give it focus. Somebody who opens
    the app and starts typing should not have to reach for the mouse first.

The other seven text-field screens deliberately do **not** auto-focus. Requesting focus
raises the software keyboard, and on a screen that leads with content somebody wants to
read -- AddArtifact's chapter list, WriteNewNote's reply preview -- that covers the thing
they came for. M3 asks for the initial focus to be *defined*, not for a field to be
grabbed; on those screens the definition is "the top of the content".

**Large text verified on a device rather than reasoned about.** Two passes:

A static one first, since the failure mode is a fixed height around text. All 23 fixed
vertical dimensions outside `Spacer`s are icons, images and progress indicators -- 12 to
40dp `.size()` calls, a 200dp image, a 180dp `heightIn` cap. Nothing wraps text in a fixed
box.

Then at `font_scale 2.0` on an API 36 emulator, three screens: onboarding, the message
list, and a chat room. All reflow without clipping. The chat room is the useful one --
system messages wrap to two lines and their timestamps and chevrons stay aligned, the
composer keeps its full width, and the transcript stays readable. `font_scale` was put
back to 1.0 afterwards.

The physical device attached to this machine was left alone. `font_scale` is a
system-wide setting and changing it on somebody's actual phone to test an app is not a
reasonable thing to do; a fresh emulator was booted for it instead.

**An unrelated flaky test, measured and left alone.** `ChronicleApplyJvmTest > an answered
catch-up leaves one line, whatever it took to deliver` failed once during this commit's
verification with

    expected:<[chronicleRequested, chronicleReceived]> but was:<[chronicleReceived, chronicleRequested]>

and reproduces at **1 failure in 8** consecutive `--rerun` invocations on this tree. Both
transcript lines are written within the same second and the DAO's ordering has no
documented tie-break, so either order can come back. That is chronicle and database code;
nothing in this branch touches it. Whether it is a test bug or a real one -- two lines
swapping places in a user's transcript on reload would be a defect -- wants deciding by
somebody in that code, so it is filed rather than patched here.

**Tests.** 944 pass, 595 jvm over 72 classes and 349 android over 44, unchanged. Focus and
window insets are properties of a running composition; there is no Compose UI test
infrastructure here, and a test asserting the modifier is present would restate the diff.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 01:18:23 +02:00
Kgothatso NgakoandClaude Opus 5 4fe47c7d46 fix: derive every call-site colour from its container, ending nine contrast failures
Phase 3, first step, of docs/material-design-conformance.md. The generated palette was
already sound -- every `onX`-on-`X` pair in all six schemes clears 4.5:1 -- and every
failure in the app came from a colour reached for at the call site instead of derived from
what it sits on.

**The worst one made the app's most important rows invisible.** `ProposalListScreen` put a
`ListItem` inside a `Card` and overrode only the card's container:

    Card(colors = CardDefaults.cardColors(containerColor = primaryContainer)) {
        ListItem(colors = ListItemDefaults.colors(containerColor = Color.Transparent),

`cardColors(containerColor = …)` does derive `contentColor = contentColorFor(…)`, so
`LocalContentColor` inside the card was correct. `ListItem` does not read
`LocalContentColor`. Its headline comes from `ListTokens.ItemLabelTextColor`, which is
`onSurface`, and in the light scheme `onSurface` and `primaryContainer` are both `#1B1B1B`.
Measured on that card:

    headline (onSurface)          1.00:1     invisible
    leading icon (primary)        1.22:1
    supporting (onSurfaceVariant) 1.84:1
    "could not be read" (error)   2.67:1
    onPrimaryContainer            4.61:1     the only one that worked

Four of five below the floor, and the card is applied to exactly `proposal.awaitsYou` --
the proposals waiting on your signature. Dark was fine throughout, because there
`primaryContainer` is black, so this only ever showed in the light scheme.

The card's colours are now computed once and everything inside derives from
`cardColors.contentColor`: the six `ListItemColors` slots, the leading icon tint, the
"Review" label, and the unreadable-count line. `primaryContainer` is kept as the highlight
so this stays a fix rather than a restyle -- `secondaryContainer`, the brand gold, would
read more like "this needs you", and that is a design call recorded in a comment rather
than taken here.

On the highlighted card the failure state loses its red, because `error` is 2.67:1 there.
The signal survives in the icon and in the sentence "could not be read", which is the more
robust cue anyway and the only one available to somebody who cannot distinguish the red.

**`HomeScreen`'s top bar lost its override entirely.** `containerColor = primaryContainer`
with `titleContentColor = primary` is `#000000` on `#1B1B1B`: **1.22:1**, a black title on
a near-black bar. `TopAppBarDefaults` gives `surface`/`onSurface` and needed no help.

**Three of the four `alpha = 0.5f` sites were not text, which changes what they failed.**
The audit called them caption text; they are `CircularProgressIndicator` colours, so the
threshold is 3:1 rather than 4.5:1. At 2.49:1 they fail either way, but the plan said the
wrong thing and is corrected. The one that really is text -- `ArticleCard`'s published-at
timestamp at `alpha = 0.7f`, 3.96:1 -- is the fourth. All five now use `onSurfaceVariant`
at full opacity, 7.25:1, which is the role for secondary text and needed no alpha to
become one.

**The LIVE badge was a hand-mixed red.** `Color(0xFFE53935)` with a white label is 4.23:1,
under the floor for `labelSmall`. `error`/`onError` is the role for a red that has to be
read and is 6.46:1.

**The avatar picker used a content colour as a background.** `onSurface` at 50% composited
to a mid grey 2.49:1 from the unselected cells beside it -- so which emoji was selected was
close to unreadable. Now `secondaryContainer`, M3's role for a selected item. Worth being
straight about the limit: that role is 1.65:1 against the surface in this palette, which M3
accepts because its own selected states carry a second cue, an outline or a checkmark. This
grid has neither. Adding one is component work, and the comment and the plan both say so
rather than leaving it looking finished.

**Three colours stay hardcoded, and each says why at the site.** A new
`// m3-color-exempt: <reason>` marker, matching the spacing convention from phase 2, and
the audit honours it:

  - `QRCodeView` -- a QR code is read by a camera. Scanners need maximum luminance
    contrast between the modules and their background, and under dynamic colour
    `onSurface`/`surface` could be two mid tones and unscannable.
  - `FullScreenImageViewer`'s close button -- it floats over an arbitrary photograph, so
    no role is safe behind it. A translucent scrim with white on it is M3's own
    full-screen media treatment and the only pairing that holds over both a white sky and
    a black one.
  - `LoadingAsyncImage`'s spinner, but only when a blurhash placeholder is behind it. With
    no placeholder the surface is known and the role is used.

Exemptions belong at the call site: the reason travels with the code and a reviewer sees it
in the diff that adds it, rather than in a list of file names in the audit script.

**Two colours were tokenised without moving a pixel.** `Color.Black` on the blank route's
`Surface` and on the image viewer's backdrop are both `scrim`, which is `#000000` in every
one of this app's six schemes. Same bytes, and the value now travels with the theme.

**A new assertion for the case the others structurally cannot catch.** A translucent
container has no contrast ratio of its own -- it has one only once composited -- so
`ColorSchemeContrastTest` grows an eleventh test that composites the two remaining tinted
containers over `surface` and measures the result, in all six schemes, naming the call site
in the failure. The pairings this commit *fixed* are not restated: once the proposal card
derives its colours, the pair it produces is `onPrimaryContainer` on `primaryContainer`,
which the first assertion already walks.

**Audit budget for hardcoded colours ratcheted 9 -> 0**, dated in the file.

**Tests.** 944 pass, 595 jvm over 72 classes and 349 android over 44, up from 942/594/348.
`:composeApp:compileDebugKotlinAndroid` builds, `m3-audit.sh --check` exits 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 00:45:01 +02:00
Kgothatso NgakoandClaude Opus 5 1bd5ad960f docs: record what phase 2 built, and why the audit changed shape
The plan's phase 2 was written before the migration ran and assumed the work was
mostly a sweep for off-grid numbers. It was not: 10dp and 20dp dominate the tree and
both are already on the M3 scale, so only 89 of 527 were off-grid at all. The section
now says what was actually built -- the scale, the two migrations, and the reason the
audit's value-based classification had to become a shape-based one -- along with the
0.03% pixel diff that shows the sweep moved nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 00:37:30 +02:00
Kgothatso NgakoandClaude Opus 5 52b57769e1 feat: adopt MaterialExpressiveTheme, and give shape, type and motion a named home
Phase 1, steps 3, 4 and 6 of docs/material-design-conformance.md. `TorchTheme` passed
`MaterialTheme` a colour scheme and a typography and nothing else, so shape and motion were
whatever the library defaulted to and there was nowhere to write down what any of it was
for.

**Expressive, by decision rather than by drift.** The plan deliberately left
`MaterialExpressiveTheme` vs `MaterialTheme` open, because it changes component defaults
app-wide and is a product call. Put to the product owner on 2026-09-08 and answered
expressive. The pinned material3 1.10.0-alpha05 ships the whole set -- `ButtonGroupKt`,
`SplitButtonKt`, `FloatingToolbarKt`, `LoadingIndicatorKt`, `ShortNavigationBarKt`,
`WideNavigationRail`, `MaterialShapesKt` -- and the tree already opts into
`ExperimentalMaterial3ExpressiveApi` in 66 places, so this makes explicit what the imports
had already assumed.

**All four slots are passed explicitly, and that is the point.**
`MaterialExpressiveTheme` defaults its colour scheme to `expressiveLightColorScheme()` and
its shapes and typography likewise -- Material's values, not this app's. Leaving any slot
to that default is the same class of accident as the twelve unassigned fixed roles fixed
two commits ago: it compiles, it renders, and it renders somebody else's design.

**No visual change on the screens checked, and that is worth stating rather than
assuming.** Measured on the API 36 emulator: the "Invite a Friend" button is byte-identical
before and after -- same fill `#4E5E8B`, same 357px box at the same y -- because the
expressive default for a `Button` at default size matches the baseline in this version.
What expressive actually buys is elsewhere: `LocalUsingExpressiveTheme` gating component
behaviour, the three increased shape steps, the fifteen `...Emphasized` type roles, and the
components phases 5 to 7 are built on.

**`MantraShapes` is baseline `Shapes()`, on evidence.** The corners hand-written across the
tree already land on the M3 scale --

    RoundedCornerShape(4.dp)   x3   = extraSmall
    RoundedCornerShape(12.dp)  x11  = medium
    RoundedCornerShape(16.dp)  x2   = large
    RoundedCornerShape(30.dp)  x1   ~ extraLarge (28dp)

-- so overriding the scale would restyle the app for no reason. What is wrong is that they
are literals, which is how the last one drifted two units off the scale and why none of
them can move per breakpoint later. `Shape.kt` documents the eight steps and what each is
for; migrating those seventeen call sites is a later phase, and this is what they migrate
onto. Declaring it explicitly rather than relying on the default gives the note somewhere
to live.

**`MotionScheme.expressive()` is wired and unused.** Nothing in the app animates today --
one `animateScrollToPage`, no `AnimatedVisibility`, no navigation transitions -- so this
buys nothing yet. It is here so that when the motion phase starts, every spec comes from
the scheme rather than from a literal `tween`, and the app's feel is one decision instead
of forty.

**`Type.kt` left `com.example.ui.theme`.** It has been declaring that package while living
under `press/mantra/compose/ui/theme/`, one of three namespaces holding live UI code in
this tree. The move is mechanical; the doc comment on it is not. It records what each type
family is *for* -- `display*` for a screen's identity, `headline*` for section tops,
`title*` for headers and list headlines, `body*` for anything read as a sentence, `label*`
for **component text only** -- because the audit's finding is not that the scale is wrong
but that 92 of 240 reads are `label*` while `display*` and `headline*` carry 9 between them
across 43 screens. A UI at one pitch. The file stays baseline; the rule now has a home for
the sweep that fixes the call sites.

**The desktop unlock screen renders in the app's theme for the first time.**
`PassphraseGate` sat in the `else` branch beside `MantraApp`, which applies `TorchTheme`
itself -- so the gate composed under the default `MaterialTheme` and its
`colorScheme.error` and `typography.headlineSmall` were baseline M3. It is the first screen
a desktop user sees. `TorchTheme` now wraps both branches.

That wraps the unlocked branch twice, deliberately. `MantraApp` keeps its own `TorchTheme`
because android and ios enter through it and would lose the theme entirely if it moved out;
a second application of identical values costs one `CompositionLocalProvider` composition.
The comment says so, since the redundancy looks like an oversight.

**Dynamic colour stays on, by decision.** Also put to the product owner: on Android 12+
`dynamicColor = true` wins unconditionally, so the six schemes are used only below Android
12, on ios and on desktop, and a modern phone paints the wallpaper palette. Answered keep
as-is. A comment on the selection in `TorchTheme` now says this outright, because otherwise
the next person to change `Color.kt` and see nothing happen on their phone will assume the
change did not work.

**Tests.** 926 pass, 586 jvm over 71 classes and 340 android over 43, unchanged -- this
commit adds no assertions, because what it changes is either a library default (nothing to
assert that the compiler does not) or a doc comment. `:composeApp:compileDebugKotlinAndroid`
and `:composeApp:compileKotlinJvm` build, the debug apk installs and runs on emulator-5554
under the expressive theme, `m3-audit.sh --check` exits 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 00:17:41 +02:00
Kgothatso NgakoandClaude Opus 5 21d57eba54 feat: honour the platform's contrast setting, reaching four schemes that were dead code
Phase 1, step 2 of docs/material-design-conformance.md. `Color.kt` has carried medium-
and high-contrast variants of both themes since it was generated -- 156 colour values,
wired into `lightColorScheme`/`darkColorScheme` in `Theme.kt`, and never selected.
`TorchTheme` chose between `darkScheme` and `lightScheme` and nothing else, so a user who
turned contrast up in Accessibility settings got no change at all.

M3's accessibility foundation leads with *honour individuals*: "supporting varying
preferences and choices that allow individuals to address how their changing conditions,
individual knowledge, and varying needs are met." The work to do that was already done and
disconnected.

**The expect/actual boundary moved, because it was in the wrong place.** `themeColorScheme`
took four arguments and did two unrelated jobs -- decide the contrast-free light/dark
scheme, and decide whether to prefer a wallpaper palette. Adding contrast to it would have
meant passing six schemes across the boundary and repeating the selection table in three
actuals. It splits instead into `platformThemeContrast()` and `dynamicColorScheme()`, each
answering one narrow platform question, with the six-way table as a plain function
`appColorScheme(darkTheme, contrast)` in common code. `dynamicColorScheme` returns null
rather than falling back internally so the fallback stays in one place.

**Android reads the setting and listens for changes.** `UiModeManager.getContrast()` is
API 34; the app's minSdk is 26, so below that the answer is Standard. The float is snapped
to the nearest of the platform's three documented positions rather than matched exactly, so
a future finer-grained slider degrades to the closest scheme this app has instead of
falling back to Standard.

The `ContrastChangeListener` is the part that is easy to leave out and matters most. A
contrast change does not restart the activity and does not arrive as a `Configuration`
update, so without it the new setting would take effect on the next cold start -- which is
precisely the case the setting exists for. `context.mainExecutor` rather than
`ContextCompat.getMainExecutor`: it needs API 28, this branch is already gated on 34, and
composeApp does not declare androidx.core -- it only arrives transitively through
activity-compose, which is not a dependency to lean on.

**iOS observes the notification for the same reason** --
`UIAccessibilityDarkerSystemColorsEnabled` plus
`UIAccessibilityDarkerSystemColorsStatusDidChangeNotification`. It is a boolean, not a
slider, so iOS reports High or Standard and never Medium.

**Desktop is honest rather than complete.** Windows publishes high contrast as the
`win.highContrast.on` AWT desktop property and fires a property change when it is toggled,
so that path is real and live. macos "Increase contrast" and the linux desktop equivalents
do not reach AWT, and reading them means a native call per platform, so on those two the
answer is Standard and the file says so. This is the right place for a user-overridable
preference later; a desktop app cannot always see what the desktop was told.

**Verified on an emulator, at the pixel.** API 36, dynamic colour temporarily switched off
(see below for why that is necessary), sampling the `onPrimaryContainer` pixel of the "Skip
for now" label as `settings put secure contrast_level` moved:

    standard (0.0)   #848484     onPrimaryContainerLight
    medium   (0.5)   #A7A7A7     onPrimaryContainerLightMediumContrast
    high     (1.0)   #D0D0D0     onPrimaryContainerLightHighContrast

The three declared values exactly, and **the app was not restarted between them** -- only
the setting changed, four seconds apart. That is the listener working end to end. The probe
that switched dynamic colour off is reverted in this commit; the emulator's contrast_level
is back at 0.0.

**A finding that came out of the verification, and is not fixed here.** `TorchTheme`
defaults `dynamicColor = true`, and on Android 12+ dynamic colour wins unconditionally --
so on essentially every current Android device **none of the six schemes is used at all**
and the app renders in whatever the user's wallpaper produced. The first screenshot of this
session shows the onboarding screen in Material lavender; switching dynamic colour off
reveals the black-and-gold brand for the first time. Nobody on a modern Android has been
seeing this app's palette.

That is a product decision, not a conformance one, so it is recorded in the plan's "What
this plan does not cover" rather than changed. It does bound what this commit buys: on
Android 14+ with dynamic colour on, contrast is honoured by the platform anyway (the
`system_*` resources shift with it, confirmed on the same emulator -- buttons went
slate-blue to near-black navy). What this commit reaches is Android below 12, Android 12-13,
iOS, and desktop.

**Three new assertions.** `AppColorSchemeSelectionTest` covers the table itself, because its
failure mode is silent and specific: a scheme wired to the wrong cell still renders a
complete, plausible UI, and somebody who turns contrast up and gets the medium scheme back
cannot tell it apart from a high-contrast scheme that is not very high. It asserts each of
the six cells by identity, that all six are distinct objects (a copy-paste leaving two cells
on the same scheme would pass the first test only if it also mislabelled one), and that
`onSurface` on `surface` never *falls* as contrast rises -- the one direction that must
hold, and deliberately not the full monotonicity assertion that ColorSchemeContrastTest
explains is false.

**Not compiled: the iOS actual.** The ios targets are declared only on macos (see
docs/jvm-target.md), so `Theme.ios.kt` is written against the UIKit and Foundation bindings
rather than checked by a compiler. Its file comment says so. The android and jvm actuals of
the same two functions are compiled, and the android one is verified on a device.

**Tests.** 926 pass, 586 jvm over 71 classes and 340 android over 43, up from 920/583/337.
`:composeApp:compileDebugKotlinAndroid` and `:composeApp:compileKotlinJvm` build,
`m3-audit.sh --check` exits 0. The 54 existing `TorchTheme { }` call sites are untouched --
the new parameter is defaulted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 00:10:06 +02:00
Kgothatso NgakoandClaude Opus 5 2b0ce8d73b test: measure M3 conformance instead of asserting it, with a budgeted audit and a contrast test
Phase 0 of docs/material-design-conformance.md. Every count in that document was
produced by hand, which makes the eight phases after it opinions rather than work
with acceptance criteria. This is the harness that turns them back into numbers.

**`docs/scripts/m3-audit.sh` regenerates the whole audit, and can fail a build.**
Plain invocation reports; `--check` exits 1 when a budget at the top of the file is
exceeded. The budgets are the tree as it stands -- 11 hardcoded colours, 33 bare
`.clickable`, 18 null content descriptions, 12 unassigned colour roles -- and the
contract written into the header is that they ratchet **down**, in the same commit
that earns the reduction, and are never raised. Counts a phase has not reached yet
are `-1`, which reports but never fails. Phase 8 wires `--check` into CI, at which
point a raised budget is the diff a reviewer is looking for.

Verified both directions: `--check` exits 0 on the clean tree, and appending a
single `Color(0xFF00FF00)` to LoadingScreen.kt makes it exit 1 naming the budget.

**Two counts are reported apart from each other on purpose.** Thirteen ColorScheme
roles are never assigned in Theme.kt, and reporting that as one number would
overstate it. Twelve are the `*Fixed*` family, which default to
`ColorLightTokens.PrimaryFixed` -> `PaletteTokens.Primary90` -> `#EADDFF`, so a
monochrome app renders Material baseline lavender the moment anything reads one.
The thirteenth is `surfaceTint`, whose default is `primary` -- correct, and not a
defect. The script labels the first group "lavender" and the second "not a defect".

The `.dp` histogram splits three ways for the same reason. 527 literals: 419 on the
M3 spacing scale, 19 dimensions rather than spacing (a 1dp hairline, an avatar, an
image height), and 89 genuinely off-scale. The naive split reported 101 off-scale by
counting 1dp borders as bad spacing, which would have sent phase 2 chasing hairlines.
`DIMENSION_EXEMPT` is deliberately short and the header asks for a justification in
the commit that lengthens it.

**`ColorSchemeContrastTest` walks the real schemes, which cost a visibility keyword.**
Four assertions over all six declared schemes: every content role on its container at
4.5:1, `onSurface` on each of the seven tonal surfaces at 4.5:1, `outline` against
every surface it is drawn on at 3:1, and `primary`/`error` against `surface` at 3:1.
WCAG relative luminance from first principles -- the 0.03928 knee and the 2.4
exponent, not a gamma-2.2 approximation, because the approximation moves borderline
pairs by enough to change a verdict and the tightest pair in this tree is 4.56:1.

`Theme.kt`'s six schemes went from `private val` to `internal val` so the test can
see them. The alternative -- rebuilding the schemes inside the test from `Color.kt`'s
public values -- keeps production visibility untouched and was rejected: it would
assert the palette and miss the wiring, and the wiring is the half that fails
silently. `surfaceContainerHigh = surfaceContainerHighestLight` is a one-character
slip, compiles, and reads fine in review. A comment above the first scheme says this,
so the keyword is not quietly widened back.

**Verified that it bites.** Nudging `onSurfaceVariantLight` from `#4C4546` to
`#9C9496` -- a plausible "soften the secondary text" edit that nothing else in the
build would object to -- fails with `light: onSurfaceVariant on surfaceVariant is
2.29:1`, naming scheme, pair and ratio. Reverted; the committed value is unchanged.

**Monotonicity across the contrast ladder is deliberately not asserted.** The obvious
invariant -- high-contrast beats medium beats default for every pair -- looks right
and is false. Ten pairs move the other way, and correctly: in the light high-contrast
scheme `surfaceContainerHighest` goes darker to separate it from `surface`, which
drops its ratio against `onSurface` from 13.30 to 12.29 while raising the separation
that the change exists for. `onErrorContainer on errorContainer` drops 7.24 -> 5.19
from default to medium for the same kind of reason. Asserting the ladder would have
meant either a red test or nine exemptions; the floor is the real invariant and every
one of those values is comfortably above it. The test's doc comment records this so
the next reader does not add the assertion.

**Also not asserted: `outlineVariant`, and the call sites.** `outlineVariant` reads
1.61:1 against surface, which looks alarming and is not a defect -- M3's own baseline
sits in the same range and the role is a decorative divider, so `outline` is what
gets the 3:1 assertion. The seven call-site pairings that are genuinely below
threshold, including the 1.00:1 one in ProposalListScreen, belong to phase 3; adding
them now would mean checking in a red test.

**Doc reconciled to the script rather than the other way round.** Three hand counts
were wrong and are corrected in docs/material-design-conformance.md: 520 `.dp`
literals -> 527 (the earlier figure omitted the exempt dimensions), 90 `label*`
typography uses -> 92 (it missed `labelSmallEmphasized` and `labelLargeEmphasized`,
which are label roles too), and 101 off-scale -> 89. The phase 0 section is rewritten
from a plan into what was built, including what was decided against.

**Tests.** 914 pass, 580 jvm over 70 classes and 334 android over 42 classes, up from
906/576/69 and 330/41 -- the four new assertions, in one new class, counted once per
target because commonTest flows into both. `:composeApp:compileDebugKotlinAndroid`
builds. No app behaviour changes: the only production edit in this commit is
`private` -> `internal` on six vals.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 23:51:34 +02:00
Kgothatso NgakoandClaude Opus 5 1c02b25a07 docs: measure the UI against the M3 foundations, and phase the work that follows
A plan, not a change: what m3.material.io/foundations asks for as of its May 2026
revision, what these 43 screens actually do, and eight phases ordered so that each
one makes the next mechanical rather than judgemental.

**The spec was read, not remembered.** m3.material.io is a client-rendered SPA --
WebFetch returns an empty `<main>` and the tab URLs 404 on direct navigation -- so
the numbers here came out of a real browser session clicking through the tab
controls. That mattered: the May 2026 revision renamed window size classes to
**breakpoints** and there are now five of them rather than three (compact / medium
/ expanded / large / extra-large, at 600 / 840 / 1200 / 1600dp), renamed responsive
design to adaptive design, and published the spacing system as tokens on an 8dp
scale where `space100 = 8dp`. Writing this from memory of older M3 would have
produced a plan against a vocabulary the current spec no longer uses.

**The palette is fine; the call sites are not.** Every `onX`-on-`X` pair in all six
declared schemes clears 4.5:1, the tightest being `onPrimaryContainer` on
`primaryContainer` at 4.61:1 light and 4.56:1 dark. So the generated scheme is not
the problem and this plan does not propose a repalette. What fails is colour
decided locally, seven pairings of it, and the worst is not visible to a reviewer:

    Card(colors = CardDefaults.cardColors(containerColor = primaryContainer)) {
        ListItem(colors = ListItemDefaults.colors(containerColor = Color.Transparent),

`cardColors(containerColor = ...)` does derive `contentColor = contentColorFor(...)`,
so `LocalContentColor` inside the card is correct. But `ListItem` does not read
`LocalContentColor` -- its headline comes from `ListTokens.ItemLabelTextColor`,
which is `onSurface` -- and the call site overrides only `containerColor`. In the
light scheme `onSurface` and `primaryContainer` are both `#1B1B1B`. That is
**1.00:1**, and it is applied exactly to `proposal.awaitsYou`, so the proposals
waiting on your signature are the ones rendered invisible. `HomeScreen`'s
`titleContentColor = primary` on `containerColor = primaryContainer` is the same
mistake at 1.22:1. Ratios were computed rather than eyeballed; the script is in the
Phase 0 deliverable.

**Twelve colour roles fall through to Material baseline lavender.** `Color.kt`
never assigns `primaryFixed`, `primaryFixedDim`, `onPrimaryFixed`,
`onPrimaryFixedVariant` or the secondary/tertiary equivalents, so
`lightColorScheme()` defaults them to `ColorLightTokens.PrimaryFixed` ->
`PaletteTokens.Primary90` -> `#EADDFF`. Nothing reads them today, which is why it
has never been noticed; the trap springs the first time an expressive component
does. Read out of the pinned `material3-desktop-1.10.0-alpha05-sources.jar` rather
than assumed.

**Four of the six declared schemes are unreachable.** The medium- and high-contrast
variants are written out in full in `Color.kt` -- 78 colour values -- wired into
`lightColorScheme`/`darkColorScheme` in `Theme.kt`, and then never selected:
`TorchTheme` chooses between `darkScheme` and `lightScheme` only. The work to
honour a platform contrast setting is already done and disconnected.

**10dp and 20dp are not the problem they look like.** They are the two dominant
spacing values (132 and 115 uses) and both are *on* the M3 scale, as `space125` and
`space250`. The plan says so rather than proposing a sweep that would change
nothing. What is wrong is that none of the 520 `.dp` literals records whether it is
padding, a gap or a margin -- the three categories the spec gives different rules
to -- so nothing can be adapted per breakpoint later. About 101 are off-scale
(50dp x 53, 15dp x 14, 5dp x 10 and so on), and `Modifier.height(50.dp)` appears 49
times as the same copied spacer above the same copied error message.

**Findings that were measured and then dropped.** `outlineVariant` reads 1.61:1
against surface and `secondaryContainer` 1.65:1, both of which look alarming and
neither of which is a defect: M3's own baseline sits in the same range, and the 3:1
rule the spec gives is for clustered interactive containers, not dividers or tonal
surfaces. `onSurface.copy(alpha = 0.38f)` is the specified disabled opacity and the
spec exempts disabled states from contrast entirely. Reporting these would have
padded the count and cost the reader trust in the rest.

**The rest of the audit, in counts.** 334 string literals in composables against 2
`stringResource` calls, with title case throughout ("Edit Profile", "New Chat") where
the style guide asks for sentence case. Zero `Snackbar` across 26 `Scaffold`s. 16
copies of `Text("Something went wrong")`, none of which offers a retry. 90 of 240
typography reads on `label*` roles, which are for component text, while `display*`
and `headline*` carry 9 uses between them across 43 screens. 33 bare
`Modifier.clickable` with no minimum target, two of them text-height. Two
`BoxWithConstraints` and no window-size handling at all, on a project with a desktop
target whose own entry point already says so in a comment.

**Eight phases, ordered by what each unblocks.** 0 baseline harness, 1 theme,
2 spacing tokens, 3 accessibility floor, 4 content, 5 states and feedback,
6 adaptive layout, 7 motion, 8 guard rails. Tokens come before the call sites that
consume them; the accessibility floor comes before the adaptive work that would
otherwise double the surface to fix; guard rails come last so they lock in real
state rather than aspiration. Phase 6 is the only one that cannot be done
mechanically and the only one marked not reversible alone.

**What it deliberately does not decide.** Whether the target is
`MaterialExpressiveTheme` or `MaterialTheme` -- the pinned material3 ships the full
expressive set and the code already opts into `ExperimentalMaterial3ExpressiveApi`
in 66 places, but it changes default component shapes and sizes app-wide, so it is a
product call and Phase 1 raises it rather than answering it. Also out of scope:
whether the monochrome palette is right, the per-component specs, iOS (which only
builds on a mac, and whose HIG asks 44dp where M3 asks 48dp), and the three package
namespaces the UI currently lives across.

No code changes. `docs/README.md` gains the row and the closing paragraph's note on
how this one relates to the others.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 23:44:32 +02:00