claudecode-omc 5.6.6 → 5.6.8

package/.local/skills/h5-to-swiftui/references/css-to-swiftui-map.md

@@ -0,0 +1,205 @@
+# CSS → SwiftUI Mapping Reference — Stage 4
+
+This is the lookup table used by the Stage 4 LLM prompt and the idiomatic-lint
+checker. Accuracy is critical — this directly drives code generation. Every row
+includes a caveat column because a mapping without its caveat is incomplete.
+
+Source: findings.md RQ5 (kean.blog; Hacking with Swift; Swift with Majid;
+swiftuifieldguide; Apple WWDC22-10056; tonsky.me; fatbobman).
+
+---
+
+## Flexbox → SwiftUI
+
+| CSS property / value | SwiftUI equivalent | Caveat |
+|---|---|---|
+| `display: flex; flex-direction: row` | `HStack(alignment:, spacing:)` | Default `HStack()` spacing is non-zero (system-defined); **always pass `spacing: 0`** then add explicit spacing between children |
+| `display: flex; flex-direction: column` | `VStack(alignment:, spacing:)` | Same spacing caveat — pass `spacing: 0` |
+| `flex-direction: row-reverse` | `HStack` + `.environment(\.layoutDirection, .rightToLeft)` or reverse the child array | Prefer reversing child array when order is data-driven |
+| `flex-direction: column-reverse` | `VStack` + reversed child array | No native reverse stack; reversing in data source is cleanest |
+| `justify-content: flex-start` | Default (leading) | No modifier needed |
+| `justify-content: flex-end` | `Spacer()` before first child | `Spacer()` expands to fill available space |
+| `justify-content: center` | `Spacer()` + children + `Spacer()` | Or `.frame(maxWidth: .infinity, alignment: .center)` on the container |
+| `justify-content: space-between` | `Spacer()` between each pair of children | Must insert N−1 spacers manually |
+| `justify-content: space-around` | `Spacer()` before first, between each, after last | Each spacer gets equal weight; use `Spacer(minLength: 0)` |
+| `justify-content: space-evenly` | `Spacer()` at all gaps including edges | Same as `space-around` implementation in SwiftUI |
+| `align-items: flex-start` | `HStack(alignment: .top)` / `VStack(alignment: .leading)` | |
+| `align-items: center` | `HStack(alignment: .center)` / `VStack(alignment: .center)` | `.center` is the default for HStack |
+| `align-items: flex-end` | `HStack(alignment: .bottom)` / `VStack(alignment: .trailing)` | |
+| `align-items: stretch` | Default HStack/VStack behavior for views with no explicit frame | Add `.frame(maxWidth: .infinity)` on children that need to stretch |
+| `align-items: baseline` | `HStack(alignment: .firstTextBaseline)` | Also `.lastTextBaseline`; applies only to text-bearing children |
+| `align-self: <value>` | `.alignmentGuide(alignment, computeValue:)` on the individual child | No direct `align-self` equivalent; alignment guides are complex — use only when necessary |
+| `flex-grow: 1` (uniform on all siblings) | `.frame(maxWidth: .infinity)` (in HStack) or `.frame(maxHeight: .infinity)` (in VStack) | Only correct when all siblings have the same grow ratio |
+| `flex-grow` (non-uniform ratios) | **Custom `Layout` protocol (iOS 16+)** | See "When you MUST use custom Layout" section below |
+| `flex-shrink: 0` | `.fixedSize()` or explicit `.frame(width:, height:)` | Prevents the view from shrinking below its ideal size |
+| `flex-shrink: 1` (default) | Default SwiftUI behavior | SwiftUI views compress by default when space is tight |
+| `flex-basis: <value>` | `.frame(width: value)` / `.frame(height: value)` | Approximate only; no exact CSS `flex-basis` semantics in SwiftUI |
+| `flex-wrap: wrap` | **Custom `Layout` protocol (iOS 16+)** — `FlowLayout` | No `LazyHGrid`/`LazyVGrid` equivalent for true wrapping; see FlowLayout sketch below |
+| `flex-wrap: nowrap` | Default HStack/VStack (no wrapping) | |
+| `gap: <value>` | `spacing: value` parameter on HStack/VStack | Both row-gap and column-gap map to the same `spacing` param — if they differ, use custom Layout |
+| `row-gap: <value>` | `spacing: value` on VStack | |
+| `column-gap: <value>` | `spacing: value` on HStack | |
+| `order: <n>` | Reorder child array in data source | SwiftUI renders children in declaration order; no runtime reorder modifier exists |
+
+---
+
+## CSS Grid → SwiftUI
+
+SwiftUI's grid support is intentionally limited. Know the ceiling.
+
+| CSS Grid construct | SwiftUI equivalent | Caveat |
+|---|---|---|
+| `grid-template-columns: repeat(N, 1fr)` | `LazyVGrid(columns: Array(repeating: GridItem(.flexible()), count: N))` | Only works for uniform fraction columns; not for mixed units |
+| `grid-template-columns: auto-fill minmax(min, max)` | `LazyVGrid(columns: [GridItem(.adaptive(minimum: min, maximum: max))])` | `.adaptive` fills available width automatically |
+| `fr` ratios (non-uniform, e.g. `1fr 2fr 1fr`) | **Custom `Layout` protocol (iOS 16+)** | No `LazyVGrid` equivalent; fr ratios require measuring total space and distributing proportionally |
+| `grid-template-areas` | Not supported in LazyVGrid/Grid | Use `ZStack` + `.position` for named-area layouts, or custom Layout |
+| `grid-column: span N` (eager Grid) | `.gridCellColumns(N)` on the child | Only works inside `Grid` (eager), not `LazyVGrid` |
+| `grid-row: span N` | Not supported in LazyVGrid | Requires `Grid` (eager) or custom Layout |
+| Explicit line placement (`grid-column: 2 / 4`) | Not supported natively | Custom Layout required |
+| Auto-placement (dense) | LazyVGrid default | LazyVGrid uses source order auto-placement; no `grid-auto-flow: dense` |
+| `gap` / `column-gap` / `row-gap` | `spacing` on `LazyVGrid` or `Grid` | Sets both axes uniformly; split-axis gap requires custom Layout |
+| `Grid` (eager, iOS 16+) | `Grid { GridRow { … } }` | Full alignment control; use for small, known-count grids |
+| `LazyVGrid` | `LazyVGrid(columns:, spacing:)` | For large/dynamic lists; less alignment control than `Grid` |
+
+---
+
+## Positioning → SwiftUI
+
+| CSS value | SwiftUI equivalent | Caveat |
+|---|---|---|
+| `position: static` (default) | Default SwiftUI layout flow | No modifier needed |
+| `position: relative` + `top/left/right/bottom` | `.offset(x:, y:)` | `.offset` shifts visually but preserves the layout space — the element still occupies its original slot; this matches CSS `relative` semantics |
+| `position: absolute` + `top/left/width/height` | `ZStack` + `.position(x: left + width/2, y: top + height/2)` | **`.position()` takes CENTER coordinates, not top-left.** Compute: `cx = left + width/2`, `cy = top + height/2`. Must be inside a `ZStack` or the position is relative to the parent frame |
+| `position: fixed` | `.overlay(alignment:)` on the root view, or `.safeAreaInset(edge:)` | Fixed elements must be moved outside the scrollable content entirely; common for navbars and tab bars |
+| `position: sticky` | Manual: `onScrollGeometryChange` (iOS 18+) or `ScrollViewReader` + preference key | No built-in sticky modifier before iOS 18 |
+| `z-index: <n>` | `.zIndex(n)` | **Only affects sibling ordering within the same `ZStack`.** A `zIndex` on a view nested inside a VStack has no effect relative to views outside that VStack |
+| `inset: 0` (fill parent) | `.frame(maxWidth: .infinity, maxHeight: .infinity)` inside a ZStack | |
+| `transform: translate(x, y)` | `.offset(x:, y:)` | |
+| `transform: scale(n)` | `.scaleEffect(n)` | Scales visually; does not affect layout space |
+| `transform: rotate(deg)` | `.rotationEffect(.degrees(deg))` | |
+
+---
+
+## Box-model drift — the four sources of invisible divergence
+
+These are not missing mappings — they are cases where the CSS and SwiftUI
+constructs look equivalent but behave differently. Each one causes layout
+divergence that passes code review.
+
+### 1. Margin collapse
+**CSS:** Adjacent vertical margins collapse to `max(m1, m2)`.
+**SwiftUI:** `VStack(spacing:)` accumulates; two views each with `.padding(.bottom, 16)` produce 32 pt gap, not 16.
+**Fix:** Use `VStack(spacing: max(m1, m2))` and remove per-child bottom padding, or set `spacing: 0` and add padding only to one side of each separator pair.
+
+### 2. Border draws inside (not outside)
+**CSS default (`content-box`):** `border` expands the element's visible size outward. The content area stays at declared width.
+**SwiftUI `.border()`:** draws _inside_ the frame, equivalent to CSS `outline`. The frame size does not change.
+**Fix:** Add `.padding(borderWidth)` before `.border()` to match CSS border-box behavior, or use `.overlay(RoundedRectangle(...).stroke(...))` which also draws inside.
+
+### 3. No native percentage sizing
+**CSS:** `width: 50%` is resolved by the containing block.
+**SwiftUI:** No `%` sizing modifier exists.
+**Fix:** Use `GeometryReader` — but **only in `.background{}` or `.overlay{}`**, never as a layout container. `GeometryReader` is greedy (takes all proposed space); using it as a primary layout view breaks parent constraints.
+
+```swift
+// Correct pattern for percentage width:
+Color.clear
+    .frame(maxWidth: .infinity)
+    .overlay(
+        GeometryReader { geo in
+            Rectangle()
+                .frame(width: geo.size.width * 0.5)
+        }
+    )
+```
+
+### 4. `line-height` vs `.lineSpacing` differ
+**CSS `line-height: 1.5` on 16px font:** applies half-leading (equal space above and below each line). Total line height = 24 px; each side gets 4 px extra.
+**SwiftUI `.lineSpacing(n)`:** adds `n` points of space _below_ each line only (no leading above the first line).
+**Conversion formula:** `lineSpacing = (cssLineHeight_px − coreTextLineHeight_px)` — i.e., the extra space only, applied as below-line gap.
+**iOS 26+:** `.lineHeight(.exact: value)` sets exact line height matching CSS semantics. Use this when `--ios-floor >= 26`.
+
+---
+
+## When you MUST use the custom `Layout` protocol (iOS 16+)
+
+These CSS patterns have **no stock SwiftUI equivalent**. Attempting to approximate
+them with HStack/VStack produces incorrect layout. Use `Layout` protocol.
+
+| CSS pattern | Why stock views fail |
+|---|---|
+| `flex-wrap: wrap` | HStack never wraps; LazyHGrid/LazyVGrid are scroll containers, not inline wrapping layouts |
+| Non-uniform `flex-grow` ratios (e.g. `flex-grow: 2` on one child, `flex-grow: 1` on others) | `.frame(maxWidth: .infinity)` distributes equally; no per-child weight |
+| Non-uniform `fr` ratios (e.g. `1fr 2fr`) | `GridItem(.flexible())` is always equal weight |
+| Radial / circular layouts | No stock radial container exists |
+
+### Minimal correct FlowLayout sketch (iOS 16+)
+
+```swift
+struct FlowLayout: Layout {
+    var spacing: CGFloat = 8
+
+    func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
+        let maxWidth = proposal.width ?? .infinity
+        var x: CGFloat = 0
+        var y: CGFloat = 0
+        var rowHeight: CGFloat = 0
+
+        for view in subviews {
+            let size = view.sizeThatFits(.unspecified)
+            if x + size.width > maxWidth, x > 0 {
+                y += rowHeight + spacing
+                x = 0
+                rowHeight = 0
+            }
+            x += size.width + spacing
+            rowHeight = max(rowHeight, size.height)
+        }
+        return CGSize(width: maxWidth, height: y + rowHeight)
+    }
+
+    func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
+        let maxWidth = bounds.maxX
+        var x = bounds.minX
+        var y = bounds.minY
+        var rowHeight: CGFloat = 0
+
+        for view in subviews {
+            let size = view.sizeThatFits(.unspecified)
+            if x + size.width > maxWidth, x > bounds.minX {
+                y += rowHeight + spacing
+                x = bounds.minX
+                rowHeight = 0
+            }
+            view.place(at: CGPoint(x: x, y: y), proposal: ProposedViewSize(size))
+            x += size.width + spacing
+            rowHeight = max(rowHeight, size.height)
+        }
+    }
+}
+```
+
+This is a production-usable starting point. Add `alignment` and RTL support as
+needed. The `cache` type is `Void` (no measurement caching) — add a `Cache` type
+when subview measurement is expensive.
+
+---
+
+## Quick-reference: CSS visual properties → SwiftUI modifiers
+
+| CSS | SwiftUI | Note |
+|---|---|---|
+| `border-radius: N` | `.cornerRadius(N)` or `.clipShape(RoundedRectangle(cornerRadius: N))` | `.cornerRadius` is deprecated in iOS 17+ for `.clipShape` |
+| `box-shadow: x y blur spread color` | `.shadow(color:, radius:, x:, y:)` | No `spread` equivalent; `radius` ≈ CSS `blur / 2` |
+| `opacity: N` | `.opacity(N)` | |
+| `background-color` | `.background(Color.token)` | Use token, not hex |
+| `color` | `.foregroundStyle(Color.token)` | `.foregroundColor` deprecated iOS 17+ |
+| `font-size` / `font-weight` | `.font(DesignTokens.Typography.body)` | Use extracted token; never hardcode `Font.system(size: 16)` |
+| `letter-spacing: N` | `.kerning(N)` | Units: CSS `em`-based vs SwiftUI `pt`-based; convert |
+| `text-transform: uppercase` | `.textCase(.uppercase)` | |
+| `text-decoration: underline` | `.underline()` | |
+| `overflow: hidden` | `.clipped()` | |
+| `border: N solid color` | `.overlay(Rectangle().stroke(color, lineWidth: N))` | Draws inside frame |
+| `pointer-events: none` | `.allowsHitTesting(false)` | |
+| `cursor: pointer` | No equivalent; tap gesture implied by `Button` | |
+| `display: none` / `visibility: hidden` | `if condition { view }` or `.opacity(0)` | `if` removes from layout; `.opacity(0)` preserves layout space — choose by CSS analogue |

package/.local/skills/h5-to-swiftui/references/design-token-extraction.md

@@ -0,0 +1,209 @@
+# Design Token Extraction — Stage 1
+
+Used by `scripts/extract-tokens.mjs`. Produces `tokens.json` (W3C DTCG format)
+and `token-gaps.json`. Both files are mandatory inputs to Stage 3 (scaffold) and
+Stage 4 (per-component rewrite). Stage 4 must never inline a value that belongs
+in `token-gaps.json` — see the token-miss rule below.
+
+---
+
+## The static ∪ runtime pipeline
+
+Two extraction passes run unconditionally. Their outputs are merged then
+normalized. Neither pass alone is sufficient.
+
+| Pass | What it gives | What it misses | How to run |
+|---|---|---|---|
+| Static parse | All _declared_ custom props, Tailwind config, Sass vars — complete enumeration including unused tokens | Values behind `calc()`, `var()` chains, media-query overrides, `@layer` override priority | Read source files: CSS `--*` props; `tailwind.config.js` `theme.extend`; `@theme` blocks (Tailwind v4); compiled `.css` output of Sass |
+| Runtime `getComputedStyle` | _Resolved_ values as the browser actually computes them — ground truth for any `calc`, `var`, inheritance, or conditional override | Tokens that are declared but never applied to a rendered element | Playwright: load each page, call `getComputedStyle` on a representative element per token class; run twice — once with `prefers-color-scheme: light`, once with `dark` |
+
+Merge rule: static gives the token namespace; runtime gives the resolved value.
+If a static token has no runtime-resolved value, keep static value with
+`"source": "static-only"` and flag in `token-gaps.json` if the value contains
+unresolved `var()` or `calc()`.
+
+Source: findings.md RQ3 (W3C DTCG draft format; Project Wallace; Style
+Dictionary v4; Tokens Studio).
+
+---
+
+## Tradeoff table
+
+| Criterion | Static parse only | Runtime only | Static ∪ runtime |
+|---|---|---|---|
+| Completeness | High — all declared tokens found | Low — only tokens applied to visible elements | High |
+| Resolved truth | Low — `var()`/`calc()` unresolved | High — browser computed values | High |
+| Dark-mode pairs | Manual inference required | Automatic (run twice) | Automatic |
+| Build required | No | Yes (Playwright + dev server or static build) | Dev server preferred; static build acceptable |
+| Speed | Fast | Slow (~5–30 s per page) | Moderate (static fast, runtime adds per page) |
+
+---
+
+## Normalization steps (run after merge, in order)
+
+### 1. Color deduplication
+Compare all color values using CIEDE2000 (ΔE00). If ΔE00 < 2 between two colors,
+they are the same perceptual token — keep the one with the more semantic name
+(e.g. `--color-primary` over `--tw-color-blue-600`) and discard the duplicate.
+This typically collapses "25 grays" from Tailwind into 4–6 semantic tokens.
+
+### 2. Spacing scale inference
+Collect all spacing values (padding, margin, gap, width/height in px/rem). Detect
+the base unit: if values cluster around multiples of 4 px (or 0.25 rem), the
+project uses a 4 px grid. Flag values that do not fit the inferred scale in
+`token-gaps.json` (they may be one-offs or errors). Map to SwiftUI `CGFloat`
+points (1 pt = 1 CSS px at 1× logical resolution).
+
+### 3. Type scale grouping
+Group font-size values by recurrence. A value appearing on 3+ elements is a
+type-scale step. Assign semantic names: `body`, `caption`, `title`, `headline`,
+`largeTitle` (follow Apple HIG naming where possible for SwiftUI
+`Font.TextStyle` matching). Record both `size` and `weight` per step.
+
+### 4. Light/dark pairing
+For each color token, pair the light-scheme resolved value with the dark-scheme
+resolved value. Unpaired tokens (no dark equivalent found) are flagged in
+`token-gaps.json` with `"issue": "no-dark-pair"`.
+
+---
+
+## `tokens.json` (W3C DTCG draft format — `$value`/`$type`)
+
+```json
+{
+  "color": {
+    "primary": {
+      "$value": "#0A7AFF",
+      "$type": "color",
+      "$description": "Brand primary, resolved from --color-primary via runtime",
+      "dark": { "$value": "#3395FF" }
+    },
+    "background": {
+      "$value": "#FFFFFF",
+      "$type": "color",
+      "dark": { "$value": "#000000" }
+    }
+  },
+  "spacing": {
+    "base": { "$value": "4px", "$type": "dimension" },
+    "md":   { "$value": "16px", "$type": "dimension" },
+    "lg":   { "$value": "24px", "$type": "dimension" }
+  },
+  "typography": {
+    "body": {
+      "$type": "typography",
+      "$value": { "fontSize": "16px", "fontWeight": "400", "lineHeight": "1.5" }
+    },
+    "title": {
+      "$type": "typography",
+      "$value": { "fontSize": "20px", "fontWeight": "600", "lineHeight": "1.3" }
+    }
+  }
+}
+```
+
+All values use CSS-native units in the DTCG file. Stage 3 (scaffold) converts to
+SwiftUI `CGFloat` / `Font` equivalents during the `DesignTokens` enum generation.
+
+---
+
+## `token-gaps.json` shape
+
+```json
+{
+  "schema": "h5-to-swiftui/token-gaps@1",
+  "gaps": [
+    {
+      "property": "border-radius",
+      "css_value": "var(--radius-card)",
+      "resolved_value": null,
+      "issue": "unresolved-var",
+      "source_file": "src/components/Card.module.css",
+      "source_line": 14,
+      "action": "manual-extraction-required"
+    },
+    {
+      "property": "color",
+      "css_value": "#9B9B9B",
+      "issue": "no-dark-pair",
+      "source_file": "src/components/Label.tsx",
+      "source_line": 8,
+      "action": "verify-dark-contrast"
+    }
+  ]
+}
+```
+
+---
+
+## The token-miss rule (hard constraint for Stage 4)
+
+> **Any CSS value with no extractable token in `tokens.json` goes to
+> `token-gaps.json` and is NEVER silently inlined by Stage 4.**
+
+Stage 4's LLM prompt must include the full `tokens.json` vocabulary and must
+instruct the model: "Use only tokens from the provided vocabulary. If a required
+value is not in the vocabulary, emit a `// TOKEN-MISSING: <property>` comment and
+use the closest token — do not hardcode the raw value."
+
+This rule exists because inlined magic numbers break:
+- Dark-mode adaptation (`.colorset` references the token name, not the hex)
+- The convergence loop's color ΔE tracking (tokens give expected values)
+- Any future design-system update
+
+A Stage 4 component that contains hardcoded color hex, raw spacing numbers, or
+raw font sizes without a corresponding `tokens.json` entry fails the idiomatic
+lint check and is reprocessed, not delivered.
+
+---
+
+## Style Dictionary → SwiftUI output (Stage 3)
+
+Stage 3 runs Style Dictionary v4 (DTCG-native) on `tokens.json` to produce:
+
+### `DesignTokens.swift` — a Swift enum namespace
+
+```swift
+// Auto-generated by extract-tokens.mjs — do not edit manually
+import SwiftUI
+
+enum DesignTokens {
+    enum Color {
+        static let primary       = SwiftUI.Color("dt/primary")
+        static let background    = SwiftUI.Color("dt/background")
+    }
+    enum Spacing {
+        static let base: CGFloat = 4
+        static let md:   CGFloat = 16
+        static let lg:   CGFloat = 24
+    }
+    enum Typography {
+        static let body  = Font.system(size: 16, weight: .regular)
+        static let title = Font.system(size: 20, weight: .semibold)
+    }
+}
+```
+
+### XCAssets `.colorset` files (dark-mode automatic)
+
+For each color token pair, Style Dictionary emits a `.colorset` directory with
+`Contents.json` containing both light and dark `value` entries. The `dt/<name>`
+asset catalog name matches the `SwiftUI.Color("dt/<name>")` initializer above.
+
+This means dark mode requires **no conditional code** in Stage 4 components —
+`DesignTokens.Color.primary` automatically resolves to the correct scheme.
+
+---
+
+## Extraction strategy by detected styling system
+
+From `stack-report.json` (`styling` field), `extract-tokens.mjs` selects:
+
+| Detected styling | Static strategy |
+|---|---|
+| `tailwind-v3` | Parse `tailwind.config.js` `theme` + `theme.extend`; resolve `colors`, `spacing`, `fontSize`, `fontWeight`, `borderRadius` |
+| `tailwind-v4` | Parse `@theme` block in the primary CSS entry point; no config file exists |
+| `css-modules` | Parse each `.module.css` file for `--*` custom properties; also scan for Compose-style utility patterns |
+| `sass` | Parse compiled CSS output (run `sass` if build script present); scan `.scss` for `$var` declarations |
+| `css-in-js` | Static parse is limited (values are runtime JS expressions); rely more heavily on the runtime `getComputedStyle` pass; flag all JS-expression values in `token-gaps.json` |
+| `plain-css` | Parse all `--*` custom properties in CSS files imported by the entry point |

package/.local/skills/h5-to-swiftui/references/high-risk-triage.md

@@ -0,0 +1,209 @@
+# High-Risk Surface Triage — Stage 1
+
+Triage runs during Stage 1 (static analysis), **before any code generation**. Its
+output is `risk-triage.json`. Every surface in the tier catalog below is evaluated
+against every discovered usage in the source. Tier assignment is final for a given
+iOS floor — it is not re-evaluated per component.
+
+Source: findings.md RQ6 (Android→iOS pilot 2507.16037; lottie-ios 4.3; rive-ios;
+Stripe iOS; Firebase iOS; Google Maps SPM; Apple WWDC; WebRTC iOS).
+
+---
+
+## Tier definitions
+
+| Tier | Name | What the skill emits | Compiler behavior | Human action required |
+|---|---|---|---|---|
+| 1 | **Auto** | Full, correct native implementation | Compiles and runs | Verify behavior, no code change expected |
+| 2 | **Assisted** | Compiling stub with `// VERIFY` comment at every deviation | Compiles; may not match source behavior exactly | Review marked deviations; test on device |
+| 3 | **Human-only** | Non-compiling stub with `fatalError` + `// OMC-CONVERSION: HUMAN-ONLY` block | **Does not compile by design** | Must be replaced before the app ships |
+
+Tier 3 stubs **must fail to ship**. Using `fatalError`/`preconditionFailure`
+ensures the Xcode build reminder is the app crashing at the stub call site during
+testing — not a subtle runtime wrong behavior that reaches users. (findings.md RQ6
+cites the 2507.16037 pilot: 43.2% of auto-converted files were invalid with no
+clean build "without substantial human effort".)
+
+---
+
+## iOS floor awareness
+
+Some conversions are only available above a minimum iOS version. When
+`--ios-floor` is below the listed floor, the tier upgrades one level (Tier 1 →
+Tier 2 if a workaround exists, Tier 2 → Tier 3 if not).
+
+| API | Minimum iOS |
+|---|---|
+| `KeyframeAnimator` | 17 |
+| `scrollTransition` | 17 |
+| `onScrollGeometryChange` | 18 |
+| Swift Charts (`Chart`) | 16 |
+| `Canvas` | 15 |
+| `Layout` protocol | 16 |
+| `AVPlayer` with HLS | 7 (always available in v1 scope) |
+
+---
+
+## Tier catalog
+
+Detection signal: file/line reference from static scan + grep of source, not
+runtime behavior. The `detect` column is what `scripts/detect-stack.mjs` and the
+Stage 1 static analyzer grep for.
+
+| Surface | Detection signal in source | Native iOS counterpart | Tier | Fidelity risk |
+|---|---|---|---|---|
+| **Lottie `.json` / `.lottie`** | `lottie-web` dep; `new Lottie.loadAnimation`; `.lottie` file references | `lottie-ios 4.3` — same asset file, `LottieAnimationView` | **1 Auto** | Low — asset file identical, timing matches |
+| **Rive `.riv`** | `@rive-app/canvas` dep; `new Rive(...)` with `.riv` file | `rive-ios` — same `.riv` asset, `RiveViewModel` | **1 Auto** | Low — asset file identical |
+| **REST + JSON** | `fetch('/api/...')`, `axios.get`, `XMLHttpRequest` JSON endpoints | `URLSession.shared.data(from:)` async/await | **1 Auto** | None — semantics equivalent; ATS flag applies to `http://` |
+| **HLS `<video>`** | `<video src="...m3u8">`, HLS.js dep | `AVPlayer` + `AVPlayerViewController` or custom `VideoPlayer` | **1 Auto** | Low — HLS is a first-class iOS media format |
+| **`localStorage` KV** | `localStorage.getItem`, `localStorage.setItem` | `UserDefaults.standard` | **1 Auto** (non-secrets only) | **Critical caveat:** auth tokens/secrets must NOT go to UserDefaults — see anti-pattern section |
+| **Chart.js / D3 charts** | `chart.js` dep; `new Chart(ctx, {type:...})`; `d3` dep with `d3.select` | Swift Charts (`Chart`) iOS 16+ | **2 Assisted** | Medium — data series ports cleanly; custom chart types (radar, custom scales) may not |
+| **Static SVG** | Inline `<svg>` elements or `.svg` file `<img>` embeds with no animation | SwiftUI `Path` / `Image(systemName:)` / `Canvas` | **2 Assisted** | Medium — simple shapes port; complex filters, patterns, and gradients require `// VERIFY` |
+| **Scroll-linked effects** | `window.addEventListener('scroll', ...)`, `IntersectionObserver`, `scroll-timeline` CSS | `.scrollTransition` (iOS 17+) / `onScrollGeometryChange` (iOS 18+) | **2 Assisted** | Medium — parallax and fade effects port; physics-based scroll effects are Tier 3 |
+| **Maps (basic region + markers)** | `google.maps.Map`, `mapboxgl.Map`, `<MapContainer>` (leaflet) basic usage | `MapKit` / `Map` SwiftUI view (iOS 17+) | **2 Assisted** | Medium — region display and pin markers port; custom tile layers, routing UI, Street View are Tier 3 |
+| **GSAP / CSS keyframes (linear/cubic)** | `gsap.to(...)` linear/cubic easing; `@keyframes` with `from`/`to` or step keyframes | `KeyframeAnimator` (iOS 17+) / `withAnimation(.easeInOut)` | **2 Assisted** | Medium — simple easing ports; spring physics, morphing, and stagger sequences are Tier 3 |
+| **`http://` REST endpoints** | `fetch('http://...')` or `axios.get('http://...')` with non-TLS scheme | `URLSession` with ATS exemption or enforce TLS | **2 Assisted** | High — ATS blocks `http://` by default; emit `// WARNING: ATS — this URL must be upgraded to HTTPS or an ATS exception added to Info.plist` |
+| **`IndexedDB` / complex storage** | `indexedDB.open(...)`, `idb` dep | No direct equivalent; use CoreData, SwiftData (iOS 17+), or SQLite | **2 Assisted** | High — data model ports; query API is completely different |
+| **Canvas 2D (non-chart)** | `canvas.getContext('2d')`, `ctx.drawImage`, `ctx.fillRect` as primary rendering | SwiftUI `Canvas` (iOS 15+) / `drawRect` in `UIView` | **2 Assisted** (simple drawing) / **3** (pixel-manipulation shaders) | High — drawing commands port individually; `getImageData`/`putImageData` pixel manipulation is Tier 3 |
+| **WebGL / WebGPU** | `canvas.getContext('webgl')`, `canvas.getContext('webgpu')`, `three.js`, `babylon.js` deps | Metal / MetalKit / RealityKit (requires GLSL→MSL translation, state model redesign) | **3 Human-only** | Critical — GLSL and WGSL do not mechanically translate to MSL; coordinate system, depth buffer conventions, and GPU state model differ; no automatable path |
+| **`requestAnimationFrame` physics** | `requestAnimationFrame` in a game loop or physics update; Matter.js, Cannon.js deps | UIKit `CADisplayLink` or custom physics engine | **3 Human-only** | Critical — frame-loop physics is architectural; no declarative SwiftUI equivalent |
+| **WebRTC** | `RTCPeerConnection`, `navigator.mediaDevices.getUserMedia`, `simple-peer` dep | `WebRTC.framework` (Google) or `LiveKit` SDK; requires entitlements + provisioning | **3 Human-only** | Critical — signaling protocol, ICE, and media pipeline require full reimplementation |
+| **Stripe.js / payment surfaces** | `@stripe/stripe-js`, `loadStripe(...)`, `CardElement` | Stripe iOS SDK + Apple Pay entitlement | **3 Human-only** | Critical — publishable key handling, webhook secrets, and PCI compliance require human audit; never auto-port |
+| **Firebase / OAuth provisioning** | `firebase/auth`, `GoogleSignIn`, `signInWithPopup` | Firebase iOS SDK / GoogleSignIn iOS; requires `GoogleService-Info.plist`, URL schemes, entitlements | **3 Human-only** | High — client IDs, redirect URIs, and entitlement provisioning cannot be inferred from web config |
+| **Analytics / ATT** | `gtag`, `mixpanel`, `amplitude`, `posthog`; any event tracking | ATT framework (`AppTrackingTransparency`); native analytics SDK | **3 Human-only** | High — ATT permission prompt must appear before any IDFA access; timing and phrasing are legally significant in some jurisdictions |
+| **`SessionStorage` / auth tokens in storage** | `sessionStorage.setItem('token', ...)`, `localStorage.setItem('authToken', ...)` | `Keychain` via `Security.framework` | **3 Human-only** | Critical — see anti-pattern section |
+
+---
+
+## Anti-pattern call-out (never emit these)
+
+These three patterns are the canonical examples of **confident, compiling, subtly
+wrong code** — the exact failure mode the skill forbids.
+
+### 1. Auth tokens in UserDefaults (not Keychain)
+```swift
+// WRONG — never emit this for auth tokens
+UserDefaults.standard.set(token, forKey: "authToken")
+
+// Correct — emit a Tier-3 stub instead
+// OMC-CONVERSION: HUMAN-ONLY
+// Reason: auth tokens must be stored in Keychain (Security.framework kSecClassGenericPassword),
+// not UserDefaults. UserDefaults is not encrypted at rest and is accessible without the
+// Secure Enclave. Port this using SecItemAdd/SecItemCopyMatching or a Keychain wrapper library.
+preconditionFailure("Token storage not implemented — see conversion-report.json")
+```
+
+### 2. ATS-dropped `http://` URLs
+```swift
+// WRONG — compiles but ATS blocks this at runtime on all iOS apps without an exception
+let url = URL(string: "http://api.example.com/data")!
+
+// Correct — emit Tier-2 stub with explicit warning
+// VERIFY: ATS blocks http:// by default. Either:
+// (a) Upgrade the server to https:// (preferred), or
+// (b) Add NSAppTransportSecurity > NSAllowsArbitraryLoads exception to Info.plist (not recommended for production).
+let url = URL(string: "http://api.example.com/data")! // ATS WARNING — see above
+```
+
+### 3. Fake-timed `withAnimation` (mimicking CSS duration with a hardcoded constant)
+```swift
+// WRONG — not an animation port, it is a guess that will look wrong on different devices
+withAnimation(.easeInOut(duration: 0.3)) { ... }
+
+// Correct for Tier-2 (when CSS timing is known):
+// VERIFY: CSS animation was 'transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1)'
+// The cubic-bezier maps to approximately .timingCurve(0.4, 0, 0.2, 1, duration: 0.3)
+// Verify visually against the reference render.
+withAnimation(.timingCurve(0.4, 0, 0.2, 1, duration: 0.3)) { ... } // VERIFY
+```
+
+---
+
+## Tier-3 non-compiling stub format
+
+Every Tier-3 stub must include the machine-parseable block. This format allows
+`conversion-report.json` to be generated by grep, not by LLM post-processing.
+
+```swift
+// OMC-CONVERSION: HUMAN-ONLY
+// surface: WebGL
+// file: src/components/Globe.tsx
+// reason: WebGL (Three.js) cannot be automatically converted to Metal/MetalKit.
+//   GLSL shaders require manual translation to MSL. GPU state model and coordinate
+//   conventions differ. Suggested native counterpart: Metal + SceneKit or RealityKit.
+// action: Replace this stub with a Metal-based implementation before shipping.
+struct GlobeView: View {
+    var body: some View {
+        fatalError("GlobeView: WebGL conversion not implemented — OMC-CONVERSION: HUMAN-ONLY")
+    }
+}
+```
+
+The `// OMC-CONVERSION: HUMAN-ONLY` marker on the first line is the grep anchor.
+Fields `surface`, `file`, and `reason` are on subsequent `//` lines in `key: value`
+format. The `fatalError` is the last statement in `body`.
+
+---
+
+## `conversion-report.json` schema
+
+Aggregated at Stage 7. One entry per triaged surface (all tiers — Tier 1/2 entries
+confirm what was auto-handled; Tier 3 entries are the required human action list).
+
+```json
+{
+  "schema": "h5-to-swiftui/conversion-report@1",
+  "generated_at": "2026-05-19T12:00:00Z",
+  "ios_floor": 17,
+  "surfaces": [
+    {
+      "surface": "WebGL",
+      "file": "Sources/App/Globe/GlobeView.swift",
+      "line": 12,
+      "severity": "critical",
+      "tier": 3,
+      "native_counterpart": "Metal + SceneKit or RealityKit",
+      "action_required": "Replace fatalError stub with Metal-based implementation; translate GLSL shaders to MSL manually"
+    },
+    {
+      "surface": "Lottie",
+      "file": "Sources/App/Onboarding/OnboardingAnimationView.swift",
+      "line": 8,
+      "severity": "none",
+      "tier": 1,
+      "native_counterpart": "lottie-ios 4.3 LottieAnimationView",
+      "action_required": "None — auto-converted; verify animation timing on device"
+    },
+    {
+      "surface": "http-endpoint",
+      "file": "Sources/App/Network/APIClient.swift",
+      "line": 34,
+      "severity": "high",
+      "tier": 2,
+      "native_counterpart": "URLSession — upgrade URL to https://",
+      "action_required": "Upgrade http:// to https:// or add ATS exception to Info.plist"
+    }
+  ],
+  "summary": {
+    "tier1_count": 3,
+    "tier2_count": 2,
+    "tier3_count": 1,
+    "human_action_required": true
+  }
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `surface` | string | Short surface name from the tier catalog (e.g. `"WebGL"`, `"Lottie"`, `"REST"`) |
+| `file` | string | Output Swift file path (not input H5 file) |
+| `line` | integer | Line number of the stub or generated call site in the Swift file |
+| `severity` | string | `"critical"` \| `"high"` \| `"medium"` \| `"low"` \| `"none"` |
+| `tier` | integer | 1, 2, or 3 |
+| `native_counterpart` | string | Specific framework/API/library to use |
+| `action_required` | string | Concrete instruction for the human reviewer |
+
+The `conversion-report.json` is the primary deliverable for communicating what a
+human must finish. The final run summary (`convergence-summary.json`) must lead
+with `"needs-human": true` and the Tier-3 count when any Tier-3 surfaces are
+present.