@hegemonart/get-design-done 1.33.6 → 1.34.1

package/reference/native-platforms.md

@@ -0,0 +1,273 @@
+# Native Platforms — Token-Bridge Spec
+
+This reference is the **token→native-code bridge**: it specifies how the canonical
+CSS-token form produced by the Phase-23 token engine
+(`scripts/lib/design-tokens/`) maps onto the three native theme systems —
+SwiftUI, Jetpack Compose, and Flutter — and pins down the **precision contract**
+that defines what "token identity preserved" means for the deterministic
+round-trip (`reference/native-platforms.md` is the authority that
+`test/suite/native-token-bridge.test.cjs` asserts against).
+
+It is the sibling of [`reference/platforms.md`](./platforms.md). Those two files
+have distinct jobs and must not be confused:
+
+| File | Job |
+| --- | --- |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge the executors reference when laying out a screen. |
+| `reference/native-platforms.md` (Phase 34.1, this file) | The token→theme **bridge** — how a design token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / Compose `Color(0x…)` / Flutter `Color(0x…)`, plus the precision contract for the round-trip. *Structural* knowledge the emitters implement. |
+
+Per **D-02** the bridge **extends** the Phase-23 engine with three new emitters
+(`scripts/lib/design-tokens/{swift,compose,flutter}.cjs`) rather than forking a
+separate native IR. There is one canonical token form (below) and one set of
+readers; the native emitters are additional *sinks* on the same facade. Per
+**D-10** the round-trip operates at the **token level** — deterministic emit +
+re-extract with documented precision — never full-view parsing and never a live
+simulator, so the default `npm test` stays green on any machine.
+
+---
+
+## 1. Purpose
+
+Phase 19 shipped platform *references* but zero generators; Phase 23 shipped a
+multi-source token reader (`css-vars` / `js-const` / `tailwind` / `figma`) that
+all normalise to a single flat `{ tokens: Record<string, string> }` map. Phase
+34.1 crosses from platform-knowledge into platform-execution: instead of each
+native executor re-deriving "how does `#3B82F6` become a SwiftUI `Color`", the
+mapping lives once here (the spec) and once in the emitters (the
+implementation), and the executors consume it. This amortizes the Phase-23 token
+investment across SwiftUI / Compose / Flutter.
+
+The canonical CSS-token form is the **single input** to all three native
+emitters. This spec maps that one input to three native theme systems and states
+the precision each mapping preserves.
+
+---
+
+## 2. Canonical input shape
+
+The emitters consume the exact map shape the Phase-23 readers return: a **flat
+`{ tokens: Record<string, string> }` object** whose keys are the design-token
+names with the leading `--` stripped (exactly as `css-vars.cjs` returns) and
+whose values are the raw token values as strings.
+
+```js
+{ tokens: { "color-primary": "#3B82F6", "space-4": "16px", "font-family-body": "Inter, system-ui" } }
+```
+
+Each emitter accepts either the full Phase-23 `TokenSet`
+(`{ tokens, source?, format? }`) **or** a bare `{ tokens }` object — it reads
+`tokenSet.tokens` and throws a `TypeError` only when no `.tokens` object is
+present.
+
+### Prefix → category inference
+
+Token **category** is inferred from the key prefix. The emitters use this table
+to decide whether a value is a color, a dimension, or a string:
+
+| Key prefix | Category | Native treatment |
+| --- | --- | --- |
+| `color-` | color | hex → native channel form (§3–§5, §6 COLOR) |
+| `space-`, `spacing-` | dimension | px → pt / dp / logical px (§6 DIMENSION) |
+| `radius-` | dimension | px → pt / dp / logical px |
+| `size-` | dimension | px → pt / dp / logical px |
+| `font-`, `text-` | typography | string pass-through (family / weight / named size) |
+| `shadow-` | other | string pass-through (composite values are non-mappable) |
+| *(anything else)* | other | value-sniffed: a `#…` value is treated as color, an `Npx` value as dimension, otherwise string pass-through |
+
+A value is **always** re-sniffed regardless of prefix, so a `#…` value under a
+non-color prefix is still emitted as a color and a `Npx` value under a non-space
+prefix is still emitted as a dimension. The prefix is the hint; the value is the
+authority. This keeps the bridge robust against arbitrary token-naming schemes.
+
+---
+
+## 3. SwiftUI mapping
+
+Target: a Swift source string exposing an `enum` of static theme constants
+(`enum GDDTheme { … }`) — colors as `Color`, dimensions as `CGFloat` points,
+typography families as `String` (and an optional `Font` helper).
+
+| Token | SwiftUI form |
+| --- | --- |
+| color `#RRGGBB` | `Color(red: R/255.0, green: G/255.0, blue: B/255.0, opacity: A/255.0)` from the 8-bit channels |
+| dimension `Npx` | `CGFloat` point literal — integer `N` (pt) |
+| font-family | `String` literal (`"Inter, system-ui"`) |
+
+Illustrative (2-line) snippet:
+
+```swift
+static let colorPrimary = Color(red: 59.0/255.0, green: 130.0/255.0, blue: 246.0/255.0, opacity: 255.0/255.0)
+static let space4: CGFloat = 16
+```
+
+SwiftUI uses normalized `0.0…1.0` channel fractions; to keep the round-trip
+**exact** the emitter writes each channel as the 8-bit numerator over `255.0`
+(e.g. `59.0/255.0`) rather than a pre-divided decimal — the re-extractor reads
+the numerator back as the integer channel, avoiding float drift. The `Color` /
+`Font` / `ViewModifier` consumption pattern (applying the constants to views) is
+the executor's job; this emitter produces the *constants*.
+
+---
+
+## 4. Jetpack Compose mapping
+
+Target: a Kotlin source string with `Color` vals, a `Shapes` block (from
+`radius-` tokens), a `Typography` block (from `font-`/`text-` tokens), and a
+`MaterialTheme` wiring (`object GDDTheme { val Colors… ; val Shapes… ; val Typography… }`).
+
+| Token | Compose form |
+| --- | --- |
+| color `#RRGGBB` | `Color(0xAARRGGBB)` long literal (alpha-first, 8 hex digits) |
+| dimension `Npx` | `N.dp` (integer dp) |
+| radius `Npx` | `RoundedCornerShape(N.dp)` inside `Shapes` |
+| typography family | `String` (fed into a `TextStyle.fontFamily` slot / `Typography`) |
+
+Illustrative (2-line) snippet:
+
+```kotlin
+val colorPrimary = Color(0xFF3B82F6)
+val space4 = 16.dp
+```
+
+Compose packs ARGB into a single `0xAARRGGBB` long; alpha is the high byte. The
+re-extractor reads the 8 hex digits straight back to the channels.
+
+---
+
+## 5. Flutter mapping
+
+Target: a Dart source string building a `ThemeData` whose `colorScheme`
+(`ColorScheme`) carries the color tokens and whose `textTheme` (`TextTheme`)
+carries the typography tokens, plus a constants class
+(`class GDDTheme { … }`).
+
+| Token | Flutter form |
+| --- | --- |
+| color `#RRGGBB` | `Color(0xAARRGGBB)` (alpha-first, 8 hex digits) |
+| dimension `Npx` | logical-px **double** — `N.0` |
+| typography family | `String` (`fontFamily: 'Inter'`) |
+
+Illustrative (2-line) snippet:
+
+```dart
+static const colorPrimary = Color(0xFF3B82F6);
+static const space4 = 16.0;
+```
+
+Flutter measures in logical pixels and keeps the value as a `double` (`16.0`),
+so — unlike pt/dp — Flutter dimensions are **not** rounded to integers; the
+fractional part survives.
+
+---
+
+## 6. PRECISION CONTRACT
+
+This section is the crux. It defines, per value category, exactly what
+information the emit → re-extract round-trip preserves. The test asserts token
+identity **within this precision** — not bit-exact floats, not lossy
+approximation. An emitter is correct **iff** `reextract(emit({tokens}))`
+reproduces every token in the identity set under these rules.
+
+### COLOR — 8-bit-per-channel, EXACT
+
+- Accepted input forms: `#RGB`, `#RRGGBB`, `#RGBA`, `#RRGGBBAA` (case-insensitive).
+- `#RGB` / `#RGBA` shorthand **expands** to `#RRGGBB` / `#RRGGBBAA` by
+  duplicating each nibble (`#3af` → `#33aaff`). This expansion is part of the
+  contract: the re-extractor recovers the **expanded** `#RRGGBB(AA)` form, so
+  `#3af` round-trips to `#33aaff` (canonically equal, the documented identity).
+- Each channel is an 8-bit integer (0–255) and is preserved **exactly** — no
+  channel may be off by one. SwiftUI stores channels as `N.0/255.0` numerators;
+  Compose/Flutter store them in a `0xAARRGGBB` literal. Both forms recover the
+  identical 8-bit channels.
+- **Alpha:** when the input has no alpha (`#RGB`/`#RRGGBB`) the emitted color is
+  **opaque** — alpha byte `0xFF` (Compose/Flutter) / `opacity: 255.0/255.0`
+  (SwiftUI). The re-extractor emits an alpha channel **only when the original
+  had one**: a 6-digit input round-trips to a 6-digit `#RRGGBB` (the implied
+  opaque alpha is dropped on the way back); an 8-digit input round-trips to the
+  8-digit `#RRGGBBAA`. This keeps `#3B82F6 → #3B82F6` an exact identity.
+
+### DIMENSION — integer pt/dp, logical-px double
+
+- Accepted input: `Npx` or a bare unit-less number (`16px`, `16`). The unit is
+  normalised to `px` on the canonical side.
+- **iOS (pt) / Android (dp):** rounded to the nearest integer, **round-half-up**
+  (`15.5px` → `16`). Because rounding is lossy for non-integers, the round-trip
+  **identity set** is restricted to integer-px dimensions (e.g. `16px`), which
+  recover exactly: `16px → 16 (pt/dp) → 16px`.
+- **Flutter (logical px):** kept as a `double` (`16px` → `16.0`), so Flutter
+  does **not** round and a fractional dimension survives. The re-extractor
+  recovers `Npx` by stripping the trailing `.0` for whole numbers.
+- The re-extractor always recovers the canonical `Npx` string form, so the
+  emit→re-extract identity for an integer dimension is `"16px" === "16px"`.
+
+### `rem` / `em` — passed through verbatim (non-mappable)
+
+`rem`/`em` values depend on a root/element font-size that the token map does not
+carry, so they are **not** converted. They are treated as **non-mappable**
+(below): emitted verbatim into a raw slot and **excluded** from the round-trip
+identity set. (A future plan may add an explicit base-size option; until then,
+verbatim pass-through is the stated, deterministic behavior.)
+
+### TYPOGRAPHY / NAMED VALUES — string pass-through
+
+`font-family`, `font-weight`, named sizes, and any other string token are
+emitted **verbatim** as a string literal and recovered **string-equal**
+(`"Inter, system-ui" → "Inter, system-ui"`). No normalisation, no quoting
+changes that alter the recovered string.
+
+### NON-MAPPABLE — verbatim, EXCLUDED from the identity set
+
+Values the emitter cannot represent as a native primitive — CSS `var(--x)`
+references, `calc(…)` expressions, gradients (`linear-gradient(…)`), and `rem`/
+`em` dimensions — are **passed through verbatim** into a raw-string slot
+(a trailing comment such as `// non-mappable: <name> = <value>` or the language
+equivalent) so no information is lost, and are **explicitly excluded** from the
+round-trip identity assertion. The contract documents them as
+"verbatim / not round-tripped": the test asserts the verbatim value appears in
+the emitted source, and does **not** assert it survives re-extraction as a typed
+token.
+
+---
+
+## 7. The round-trip (what the test locks)
+
+For each emitter the bridge guarantees:
+
+1. **Determinism.** `emit(x) === emit(x)` byte-for-byte. Keys are iterated in a
+   stable sorted order; no `Date`, no `process.env`, no filesystem, no network in
+   the emit path (D-10).
+2. **Identity within precision.** For the identity set (color + integer
+   dimension + typography), `reextract(emit({tokens}))` deep-equals `{tokens}`
+   under the precision rules above (8-bit color channels exact with `#RGB`
+   expansion; integer pt/dp; logical-px double; family/weight string-equal).
+3. **Verbatim exclusion.** Non-mappable values appear verbatim in the source and
+   are not part of the identity assertion.
+
+Each emitter module exports a symmetric re-extractor
+(`reextractSwift` / `reextractCompose` / `reextractFlutter`) that parses the
+emitted native source back into a `{ tokens }` map, so the round-trip is
+deterministic and bijective on the identity set and reusable by the Phase-34.1
+regression baseline.
+
+---
+
+## 8. Registration
+
+This reference is registered in
+[`reference/registry.json`](./registry.json) as the `native-platforms` entry
+(type `heuristic`, phase `34.1`) so the registry round-trip test
+(`test/suite/reference-registry.test.cjs`) stays green — every `reference/*.md`
+must be registered and resolve (D-05, the 33.5-01 lesson).
+
+---
+
+## 9. Cross-references
+
+- [`reference/platforms.md`](./platforms.md) — the interaction-conventions
+  sibling (navigation, safe areas, gestures, native typography). Executors read
+  **both**: this file for the token→theme bridge, that file for layout/behavior.
+- `scripts/lib/design-tokens/` — the Phase-23 token engine this bridge extends
+  (`index.cjs` facade + `css-vars` / `js-const` / `tailwind` / `figma` readers +
+  the new `swift` / `compose` / `flutter` emitters).
+- `test/fixtures/mapper-outputs/tokens.json` — the canonical token fixture the
+  round-trip test derives its map from.

package/reference/registry.json

@@ -888,6 +888,13 @@
       "type": "data",
       "phase": 33.6,
       "description": "Phase 33.6 catalog-derived OpenRouter price sub-table — per-model prompt/completion $/tok snapshot of .design/cache/openrouter-models.json; derived view, the dynamic catalog is the source of truth (D-11 registry round-trip)."
+    },
+    {
+      "name": "native-platforms",
+      "path": "reference/native-platforms.md",
+      "type": "heuristic",
+      "phase": 34.1,
+      "description": "Phase 34.1 token-bridge spec — maps the canonical CSS-token form (Phase 23) to SwiftUI Color/Font/ViewModifier, Jetpack Compose Color/Shapes/Typography/MaterialTheme, and Flutter ThemeData/ColorScheme/TextTheme, with the precision contract (color hex→8-bit channels exact, dimension px→pt/dp/logical px) defining token-identity for the round-trip."
     }
   ]
 }

package/scripts/lib/design-tokens/_native-shared.cjs

@@ -0,0 +1,206 @@
+/**
+ * design-tokens/_native-shared.cjs — shared precision-contract helpers for the
+ * native emitters (swift.cjs / compose.cjs / flutter.cjs), Phase 34.1 Plan 01.
+ *
+ * The single implementation of the PRECISION CONTRACT documented in
+ * reference/native-platforms.md, so all three emitters convert color /
+ * dimension / typography / non-mappable values identically:
+ *   COLOR      hex #RGB/#RGBA/#RRGGBB/#RRGGBBAA -> 8-bit channels EXACT;
+ *              #RGB/#RGBA expand by nibble duplication; alpha tracked.
+ *   DIMENSION  Npx | unit-less -> integer (round-half-up) + logical-px double.
+ *   TYPOGRAPHY strings -> pass-through.
+ *   NON-MAPPABLE var()/calc()/gradient/rem/em -> verbatim, excluded.
+ *
+ * Pure: no fs, no network, no Date, no process.env, no child_process (D-10).
+ */
+
+'use strict';
+
+// Markers embedded in every emitted line so the symmetric re-extractors can
+// recover the EXACT canonical token key (native identifiers are mangled, e.g.
+// `color-primary` -> `colorPrimary`, so the key must travel alongside).
+const TOKEN_MARKER = '// token: ';
+const NONMAPPABLE_MARKER = '// non-mappable: ';
+
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const PX_RE = /^-?\d+(?:\.\d+)?px$/;
+const UNITLESS_RE = /^-?\d+(?:\.\d+)?$/;
+const NONMAPPABLE_RE = /(^var\(|^calc\(|gradient\(|\b(rem|em)$|\d(rem|em)$)/i;
+
+/**
+ * Read `.tokens` from a Phase-23 TokenSet or a bare {tokens} map.
+ * @param {*} tokenSet
+ * @returns {Record<string,string>}
+ */
+function readTokens(tokenSet) {
+  if (
+    !tokenSet ||
+    typeof tokenSet !== 'object' ||
+    !tokenSet.tokens ||
+    typeof tokenSet.tokens !== 'object'
+  ) {
+    throw new TypeError(
+      'native emitter: expected { tokens: Record<string,string> } (or a Phase-23 TokenSet)',
+    );
+  }
+  return tokenSet.tokens;
+}
+
+/**
+ * Stable, sorted [key, value] entries so emit(x) === emit(x) byte-for-byte.
+ * @param {Record<string,string>} tokens
+ * @returns {[string,string][]}
+ */
+function sortedEntries(tokens) {
+  return Object.keys(tokens)
+    .sort()
+    .map((k) => [k, String(tokens[k])]);
+}
+
+/**
+ * Classify a token value per the precision contract. The value is the
+ * authority; the key prefix is only a hint (see native-platforms.md §2).
+ * @param {string} _key
+ * @param {string} value
+ * @returns {'non-mappable'|'color'|'dimension'|'typography'}
+ */
+function classify(_key, value) {
+  const v = String(value).trim();
+  if (NONMAPPABLE_RE.test(v)) return 'non-mappable';
+  if (HEX_RE.test(v)) return 'color';
+  if (PX_RE.test(v) || UNITLESS_RE.test(v)) return 'dimension';
+  return 'typography';
+}
+
+/**
+ * Expand #RGB/#RGBA shorthand to #RRGGBB/#RRGGBBAA and split into 8-bit
+ * channels. Alpha defaults to opaque (255) when absent; `hadAlpha` records
+ * whether the source carried an alpha channel so the re-extractor can emit a
+ * 6- or 8-digit hex faithfully.
+ * @param {string} hex
+ * @returns {{r:number,g:number,b:number,a:number,hadAlpha:boolean}}
+ */
+function parseHexChannels(hex) {
+  let h = String(hex).trim().replace(/^#/, '');
+  let hadAlpha = false;
+  if (h.length === 3) {
+    h = h.split('').map((c) => c + c).join('');
+  } else if (h.length === 4) {
+    h = h.split('').map((c) => c + c).join('');
+    hadAlpha = true;
+  } else if (h.length === 8) {
+    hadAlpha = true;
+  }
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  const a = hadAlpha ? parseInt(h.slice(6, 8), 16) : 255;
+  return { r, g, b, a, hadAlpha };
+}
+
+/**
+ * Recover the canonical hex from 8-bit channels. Emits 6-digit #RRGGBB when
+ * the original had no alpha, 8-digit #RRGGBBAA when it did (contract: implied
+ * opaque alpha is dropped on the way back so #3B82F6 round-trips exactly).
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @param {number} a
+ * @param {boolean} hadAlpha
+ * @returns {string}
+ */
+function channelsToHex(r, g, b, a, hadAlpha) {
+  const h2 = (n) => (n & 0xff).toString(16).padStart(2, '0');
+  const base = `#${h2(r)}${h2(g)}${h2(b)}`;
+  return hadAlpha ? `${base}${h2(a)}` : base;
+}
+
+/**
+ * Pack channels into a Compose/Flutter 0xAARRGGBB literal (uppercase digits).
+ * @param {{r:number,g:number,b:number,a:number}} ch
+ * @returns {string} e.g. "0xFF3B82F6"
+ */
+function channelsToArgbLiteral({ r, g, b, a }) {
+  const h2 = (n) => (n & 0xff).toString(16).toUpperCase().padStart(2, '0');
+  return `0x${h2(a)}${h2(r)}${h2(g)}${h2(b)}`;
+}
+
+/**
+ * Strip a 0xAARRGGBB literal back into channels.
+ * @param {string} literal e.g. "0xFF3B82F6"
+ * @returns {{r:number,g:number,b:number,a:number}}
+ */
+function argbLiteralToChannels(literal) {
+  const h = String(literal).replace(/^0x/i, '').padStart(8, '0');
+  return {
+    a: parseInt(h.slice(0, 2), 16),
+    r: parseInt(h.slice(2, 4), 16),
+    g: parseInt(h.slice(4, 6), 16),
+    b: parseInt(h.slice(6, 8), 16),
+  };
+}
+
+/**
+ * px (or unit-less) -> nearest integer, round-half-up (for pt/dp).
+ * @param {string} value
+ * @returns {number}
+ */
+function pxToInt(value) {
+  const n = parseFloat(String(value));
+  return Math.floor(n + 0.5);
+}
+
+/**
+ * px (or unit-less) -> logical-px double form string for Dart (`16` -> `16.0`).
+ * @param {string} value
+ * @returns {string}
+ */
+function pxToDouble(value) {
+  const n = parseFloat(String(value));
+  return Number.isInteger(n) ? `${n}.0` : String(n);
+}
+
+/**
+ * Recover the canonical `Npx` string from an emitted numeric form.
+ * @param {string|number} num
+ * @returns {string}
+ */
+function numToPx(num) {
+  const n = parseFloat(String(num));
+  return Number.isInteger(n) ? `${n}px` : `${n}px`;
+}
+
+/**
+ * dash-case token -> camelCase Swift/Kotlin/Dart identifier.
+ * `color-primary` -> `colorPrimary`; leading digit gets a `t` prefix.
+ * @param {string} key
+ * @returns {string}
+ */
+function swiftIdent(key) {
+  let id = String(key).replace(/[^A-Za-z0-9]+(.)?/g, (_, c) =>
+    c ? c.toUpperCase() : '',
+  );
+  if (!id) id = 'token';
+  if (/^[0-9]/.test(id)) id = 't' + id;
+  return id;
+}
+
+module.exports = {
+  TOKEN_MARKER,
+  NONMAPPABLE_MARKER,
+  HEX_RE,
+  PX_RE,
+  UNITLESS_RE,
+  NONMAPPABLE_RE,
+  readTokens,
+  sortedEntries,
+  classify,
+  parseHexChannels,
+  channelsToHex,
+  channelsToArgbLiteral,
+  argbLiteralToChannels,
+  pxToInt,
+  pxToDouble,
+  numToPx,
+  swiftIdent,
+};

package/scripts/lib/design-tokens/compose.cjs

@@ -0,0 +1,150 @@
+/**
+ * design-tokens/compose.cjs — Jetpack Compose (Kotlin) theme emitter +
+ * re-extractor (Phase 34.1 Plan 01).
+ *
+ * Consumes the canonical Phase-23 token map ({ tokens: Record<string,string> })
+ * and emits a deterministic Kotlin theme source string: `Color` vals, a
+ * `Shapes` block (radius tokens), a `Typography` block (font/text tokens), and
+ * a `MaterialTheme` wiring object — per the PRECISION CONTRACT in
+ * reference/native-platforms.md.
+ *
+ * Precision contract:
+ *   COLOR      hex -> Color(0xAARRGGBB) long. 8-bit channels EXACT; #RGB
+ *              expands; alpha 0xFF when absent.
+ *   DIMENSION  Npx -> N.dp (integer dp, round-half-up).
+ *   TYPOGRAPHY strings -> Kotlin string literal, pass-through.
+ *   NON-MAPPABLE var()/calc()/gradient/rem/em -> verbatim comment, EXCLUDED.
+ *
+ * Each emitted token line carries a `// token: <original-key>` marker so the
+ * symmetric `reextractCompose(source)` recovers the exact canonical key+value.
+ * Pure: no fs, no network, no Date, no process.env, no child_process (D-10).
+ */
+
+'use strict';
+
+const {
+  TOKEN_MARKER,
+  NONMAPPABLE_MARKER,
+  readTokens,
+  sortedEntries,
+  classify,
+  parseHexChannels,
+  channelsToArgbLiteral,
+  argbLiteralToChannels,
+  channelsToHex,
+  pxToInt,
+  swiftIdent,
+} = require('./_native-shared.cjs');
+
+const RADIUS_RE = /(^|[^a-z])radius/i;
+
+/**
+ * Emit a Jetpack Compose / Kotlin theme source string from a token set.
+ *
+ * @param {{tokens: Record<string,string>}|Record<string,string>} tokenSet
+ * @returns {string}
+ */
+function emitCompose(tokenSet) {
+  const tokens = readTokens(tokenSet);
+  const entries = sortedEntries(tokens);
+  const lines = [];
+  lines.push('// Generated by get-design-done — Jetpack Compose theme tokens.');
+  lines.push('// See reference/native-platforms.md (token-bridge precision contract).');
+  lines.push('import androidx.compose.ui.graphics.Color');
+  lines.push('import androidx.compose.ui.unit.dp');
+  lines.push('import androidx.compose.material3.Shapes');
+  lines.push('import androidx.compose.material3.Typography');
+  lines.push('import androidx.compose.foundation.shape.RoundedCornerShape');
+  lines.push('');
+  lines.push('object GDDTheme {');
+
+  // Colors
+  for (const [key, value] of entries) {
+    if (classify(key, value) !== 'color') continue;
+    const { r, g, b, a, hadAlpha } = parseHexChannels(value);
+    lines.push(
+      `    val ${swiftIdent(key)} = Color(${channelsToArgbLiteral({ r, g, b, a })}) ${TOKEN_MARKER}${key} hadAlpha=${hadAlpha ? 1 : 0}`,
+    );
+  }
+
+  // Dimensions (dp)
+  for (const [key, value] of entries) {
+    if (classify(key, value) !== 'dimension') continue;
+    lines.push(
+      `    val ${swiftIdent(key)} = ${pxToInt(value)}.dp ${TOKEN_MARKER}${key}`,
+    );
+  }
+
+  // Typography (strings)
+  for (const [key, value] of entries) {
+    if (classify(key, value) !== 'typography') continue;
+    lines.push(
+      `    val ${swiftIdent(key)} = ${JSON.stringify(value)} ${TOKEN_MARKER}${key}`,
+    );
+  }
+
+  // Non-mappable — verbatim, excluded from identity set
+  for (const [key, value] of entries) {
+    if (classify(key, value) !== 'non-mappable') continue;
+    lines.push(`    ${NONMAPPABLE_MARKER}${key} = ${value}`);
+  }
+
+  // Shapes block (from radius dimension tokens) — wires dp into RoundedCornerShape
+  lines.push('');
+  lines.push('    val Shapes = Shapes(');
+  for (const [key, value] of entries) {
+    if (classify(key, value) !== 'dimension') continue;
+    if (!RADIUS_RE.test(key)) continue;
+    lines.push(`        // ${key}: RoundedCornerShape(${pxToInt(value)}.dp)`);
+  }
+  lines.push('    )');
+
+  // Typography block (MaterialTheme wiring) — references the font tokens above
+  lines.push('    val Typography = Typography()');
+  lines.push('}');
+  lines.push('');
+  return lines.join('\n');
+}
+
+const COMPOSE_COLOR_RE = new RegExp(
+  String.raw`val \w+ = Color\((0x[0-9a-fA-F]{8})\)\s*` +
+    TOKEN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+    String.raw`(\S+)\s+hadAlpha=([01])`,
+);
+const COMPOSE_DIM_RE = new RegExp(
+  String.raw`val \w+ = (\d+)\.dp\s*` +
+    TOKEN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+    String.raw`(\S+)`,
+);
+const COMPOSE_STR_RE = new RegExp(
+  String.raw`val \w+ = ("(?:[^"\\]|\\.)*")\s*` +
+    TOKEN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+    String.raw`(\S+)`,
+);
+
+/**
+ * Recover the canonical token map from an emitted Compose source string.
+ * Non-mappable lines and the Shapes-comment lines are NOT recovered.
+ *
+ * @param {string} source
+ * @returns {{tokens: Record<string,string>}}
+ */
+function reextractCompose(source) {
+  /** @type {Record<string,string>} */
+  const tokens = {};
+  for (const line of String(source).split(/\r?\n/)) {
+    if (line.includes(NONMAPPABLE_MARKER)) continue;
+    let m;
+    if ((m = COMPOSE_COLOR_RE.exec(line))) {
+      const ch = argbLiteralToChannels(m[1]);
+      tokens[m[2]] = channelsToHex(ch.r, ch.g, ch.b, ch.a, m[3] === '1');
+    } else if ((m = COMPOSE_DIM_RE.exec(line))) {
+      tokens[m[2]] = `${m[1]}px`;
+    } else if ((m = COMPOSE_STR_RE.exec(line))) {
+      tokens[m[2]] = JSON.parse(m[1]);
+    }
+  }
+  return { tokens };
+}
+
+module.exports = { emitCompose, reextractCompose };