engine/share_code library

Share codes and deep links (research theme-engine.md §11, Recommendation 13).

50 bits = family (5) + engineVersion (6) + seed (32) + CRC-7 (7), as 10 Crockford base32 symbols shown XXXXX-XXXXX. CRC polynomial x⁷ + x³ + 1 (0x09) is primitive, so every single-symbol substitution and every transposition of two different symbols is detected. Decoding is case-insensitive, maps O → 0 and I/L → 1, and ignores hyphens and spaces. Deep link: calsee://t/CODE (lowercase scheme and host, because Android matches them case-sensitively); web form https://calsee.tech/t/CODE (parsed only; App Links / Universal Links verification is pending, docs/release/README.md).

Steered themes (engine v4) use a longer, versioned code: 125 bits as 25 symbols shown XXXXX-XXXXX-XXXXX-XXXXX-XXXXX:

bits field
4 format (steeredCodeFormat; a newer one reads as "needs update")
5, 6, 32 family, engineVersion, seed (as above)
1 centred
2 brightness (0 none, 1 light, 2 dark)
2 chroma (0 none, 1 muted, 2 balanced, 3 vivid)
3 harmony (0 none, then steeredHarmonies order)
2 + 3 × 5 colour count and IntentColor.codes
1 + 9 + 9 hue range flag, from and to degrees
18 reserved (zero)
16 CRC-16/CCITT (x¹⁶ + x¹² + x⁵ + 1) over the 109 bits before it

The CRC catches every single-symbol error and every swap of two neighbouring symbols. A steered code carries the theme's intent but not its families (the family is in the code) or its name (links may add ?name=). Builds before 2.0.0 accept only 10-symbol codes, so they reject a steered code as invalid; they never open the wrong theme.

Classes

SharePayload
Decoded share-code payload.

Enums

ShareCodeStatus
What a typed or pasted code is.

Constants

crockfordAlphabet → const String
Crockford base32 alphabet (no I, L, O, U).
deepLinkScheme → const String
Deep-link scheme (lowercase).
deepLinkThemeHost → const String
Deep-link host for themes (lowercase).
deepLinkWebHosts → const Set<String>
Web hosts whose https://<host>/t/CODE links are theme links.
legacyDeepLinkScheme → const String
Pre-release placeholder scheme, still accepted when parsing so links made by development builds keep working.
shareFamilyHero → const int
Family field value for hero themes (seed = hero id).
shareFamilyReserved → const int
Reserved family field value.
steeredCodeFormat → const int
Format number of steered (25-symbol) codes.
steeredHarmonies → const List<HarmonyScheme>
Harmony order in steered codes (stable: append only).

Functions

crc16(List<int> bits) → int
CRC-16/CCITT, polynomial x¹⁶ + x¹² + x⁵ + 1 (0x1021), MSB-first, init 0, over bits (each 0 or 1).
crc7(List<int> bits) → int
CRC-7, polynomial x⁷ + x³ + 1 (0x09), MSB-first, init 0, over bits (each 0 or 1).
decodeShareCode(String input) → SharePayload?
Decodes a share code (plain or steered), or null when it is malformed, fails its CRC, or is a steered format this build does not know (see shareCodeStatus). Callers must still check the family id and that SharePayload.engineVersion is not newer than the app's ("update the app to open this theme").
encodePayload(SharePayload payload) → String
Encodes payload (see encodeShareCode and encodeSteeredShareCode).
encodeShareCode(int familyId, int engineVersion, int seed) → String
Encodes a payload as XXXXX-XXXXX. familyId 0–31, engineVersion 0–63; seed is taken modulo 2^32.
encodeSteeredShareCode(int familyId, int engineVersion, int seed, ThemeIntent intent, {bool centred = false}) → String
Encodes a steered theme as XXXXX-XXXXX-XXXXX-XXXXX-XXXXX: familyId 0–29, engineVersion 0–63, seed modulo 2^32, and intent's generation fields (families and name are not stored).
Formats the deep link for code: calsee://t/XXXXX-XXXXX (steered codes have five groups). name adds ?name= (steered themes' display names travel this way).
Formats the web form of the link for code: https://calsee.tech/t/XXXXX-XXXXX (and name as ?name=).
normalizeShareCode(String input) → String?
Normalises user input to the 10 (or, for steered codes, 25) canonical symbols (upper case, O → 0, I/L → 1, hyphens and whitespace dropped), or null if it contains a character outside the alphabet or has the wrong length.
Parses a theme deep link (calsee://t/CODE, or the pre-release infinitecalc://t/CODE; scheme and host lowercase, the code may be any case) or a web link (https://calsee.tech/t/CODE). Returns null for anything else or a bad code. A name query parameter becomes SharePayload.name (trimmed to ThemeIntent.maxNameWords words).
shareCodeStatus(String input) → ShareCodeStatus
Whether input is a valid code, a damaged one, or one from a newer app.