← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Notes/FriendColours.md (4502B)

1# Plan: Manually set a colour for a friend
2
3## Status
4
5Not implemented. This document records the research for a future pass —
6estimated at roughly a day of work, with no architectural blockers.
7
8## How friend colours work today
9
10A friend's colour is **derived, never stored**. The whole scheme rests on
11`PlayerColor.stableColor(forAuthorID:reserved:)` (`Models/PlayerColor.swift`),
12a pure function: FNV-1a hash of the `authorID` into the nine-colour palette,
13then a linear probe forward to the first colour that is more than
14`similarHueThreshold` (90°) of hue away from every reserved colour, degrading
15to exact-match avoidance and finally to the raw hashed colour when the
16palette is too crowded.
17
18Two consumers:
19
201. **Avatars** — `FriendAvatar.avatar(for:)` (`Views/FriendAvatarView.swift`)
21   colours the friend-list/picker/share-sheet avatar with
22   `stableColor(forAuthorID:reserved: [])`. The symbol is hashed off a
23   distinct seed string (`"symbol-\(authorID)"`) so symbol and colour vary
24   independently.
252. **In-game roster** — `PlayerRoster.applyRoster`
26   (`Models/PlayerRoster.swift`) walks the participants in sorted-authorID
27   order, threading a running `taken` set seeded with the local user's
28   preferred colour (`PlayerPreferences.color`, synced across the user's
29   devices via iCloud KVS). The result is a pure function of
30   (participant set, preferred colour), both identical across the user's
31   devices — so every device derives the same colour for a friend **with no
32   persisted or synced mapping**, and a friend keeps their colour across
33   games unless a lower-sorted collaborator collides with them.
34
35That "no persisted colour state" invariant is the one real cost of the
36feature: once overrides exist, roster output depends on local data plus sync
37timing, so two devices can briefly disagree after a pin until the sync lands.
38
39## The pieces
40
41### Easy
42
43- **Storage.** Add an optional `colorID: String` attribute to `FriendEntity`
44  (`CrossmateModel.xcdatamodeld`). An added optional attribute is handled by
45  automatic lightweight migration.
46- **Picker UI.** A colour submenu in the friend row's ellipsis menu in
47  `FriendsView`. `PlayerColor.palette` is already picker-ordered (sorted by
48  hue) and `PuzzleView` (~line 947) has an existing colour-picker menu to
49  crib from, including the checkmark-on-current convention.
50- **Avatar override.** `FriendAvatar.avatar(for:)` takes an optional
51  override colour; the call sites that should honour it (`FriendsView`,
52  `FriendPickerView`, `GameShareItem`) all have the `FriendEntity` in hand.
53
54### Substantive
55
56- **Roster pinning.** `applyRoster` fetches overrides from Core Data and
57  treats them as *pinned*: seed `taken` with the local colour plus all pins,
58  assign pinned friends their colour directly, and let the existing probe
59  walk the unpinned friends around them. Design decisions to settle:
60  - An explicit pin should win even when it collides with the local user's
61    own colour or another friend's pin — the user did it on purpose.
62  - Two friends pinned to the same colour is the user's prerogative; don't
63    fight it.
64  - Pinning one friend deterministically bumps some auto-assigned friends to
65    new colours (their probe now starts from a different `taken` set). This
66    is inherent and fine, but worth knowing.
67- **Cross-device sync.** Without sync, iPhone and iPad disagree about a
68  friend's colour. The precedent is the block flag: it syncs across the
69  user's own devices as a `Decision` record in the account zone
70  (`SyncEngine.enqueueDecision(kind: "block", key: authorID)`), projected
71  back onto `FriendEntity` by the `kind` switch in
72  `RecordSerializer.applyDecisionRecord`. A `"color"` kind is maybe 30 lines
73  following that template:
74  - `enqueueDecision` already accepts a `payload: String?` — carry the
75    `colorID` there.
76  - The Decision record name is kind+key, so a re-pin for the same friend
77    overwrites the prior decision — last write wins, which is the behaviour
78    we want.
79  - Clearing a pin (back to automatic) can ride
80    `enqueueDecisionDeletion(kind:key:)`, which also already exists.
81
82## Suggested order
83
841. Model attribute + `applyDecisionRecord` `"color"` case (so the projection
85   exists before anything writes it).
862. Roster pinning in `applyRoster`, with `PlayerRosterTests` coverage for
87   the pin-wins and bump-the-others cases.
883. Avatar override plumbing.
894. Picker UI in `FriendsView`, writing the entity and enqueuing the
90   Decision.