claudecode-omc 5.6.5 → 5.6.7

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.

package/.local/skills/h5-to-swiftui/references/render-equivalence-calibration.md

@@ -0,0 +1,193 @@
+# Stage 2.5 — Render-Equivalence Calibration
+
+**Why this exists.** A simulator screenshot and a Playwright screenshot of
+the "same" screen are *not* comparable rasters. Diffing them directly makes
+every metric meaningless and the loop oscillates on non-defects. Calibration
+defines the exact normalization that makes them comparable, and **measures
+the best achievable cross-renderer agreement** so Stage 5 gates against a
+real number instead of an asserted constant.
+
+## The non-comparability sources (all must be neutralized)
+
+| Source | H5 (Playwright/WebKit) | iOS (simctl/SwiftUI) | Fix |
+|---|---|---|---|
+| Chrome | no status bar / home indicator | full framebuffer incl. status bar, notch, home indicator | crop simulator content rect via known safe-area insets for `--device` |
+| Scale | logical px × `deviceScaleFactor` | physical px (e.g. @3x) | resample **both** to a common logical raster (device logical pt × fixed scale) with an **identical filter** (Lanczos3 both sides) |
+| Color | sRGB-tagged PNG | Display-P3 framebuffer | convert P3 → sRGB (relative colorimetric) before any ΔE |
+| Coords | DOM bbox in CSS px @ logical viewport | view frame in screen pt | apply `transform` (scale + safe-area offset) DOM-bbox → screen-rect |
+| Text raster | Skia glyphs | CoreText glyphs | irreducible — handled in Stage 5 by judging text regions on layout-box IoU + resolved token-color ΔE, NOT glyph-raster SSIM |
+
+## Calibration procedure
+
+Inputs: `assets/calibration/` ships a **hand-built known-correct SwiftUI
+screen** + its **H5 twin** (must include both a text block and a non-text
+color/shape block).
+
+1. Render H5 twin via `capture-reference.mjs` settings; render the SwiftUI
+   twin via `sim-screenshot.sh` for `--device`.
+2. Apply the normalization pipeline above → two co-registered logical
+   rasters + the `transform`.
+3. Run `pixel-diff.mjs` on the *known-correct* pair. The result is the
+   **best achievable** cross-renderer agreement for this exact toolchain:
+   - `floor.ssim_nontext` — SSIM over non-text regions (expect ≥ ~0.98)
+   - `floor.deltaE_p95` — 95th-pct CIEDE2000 over color regions
+   - `floor.text_iou` — layout-box IoU achievable for text regions
+   - `floor.ssim_global` — whole-screen SSIM of a *correct* screen (this is
+     the realistic ceiling, typically **< 0.995**, often ~0.97–0.99 with text)
+4. Sanity bound: if the known-correct pair cannot beat conservative bounds
+   (`ssim_nontext ≥ 0.95`, `text_iou ≥ 0.9`), the toolchain is **not
+   measurable** → write `blocked.json` and STOP. Never grade real screens
+   against an unproven metric.
+5. **Flat-content guard**: SSIM is insensitive to a uniform mean shift on
+   near-zero-variance (effectively flat) images — a clearly-divergent solid
+   pair can still score ~0.95. If BOTH normalized images are effectively flat
+   (luma variance below the flat threshold on each side), the floor is
+   unreliable → `blocked.json` + STOP, never a falsely-high floor. This is
+   why the bundled calibration content is **textured** (text + a multi-color
+   stripe region), not flat solid blocks — see
+   `../assets/calibration/README.md`.
+
+## `calibration.json` schema (consumed by Stage 5)
+
+```json
+{
+  "schema": "h5-to-swiftui/calibration@1",
+  "pinned": {
+    "sim_runtime": "iOS 17.5 (21F79)",
+    "device": "iPhone 15 Pro",
+    "logical_size": [393, 852],
+    "render_scale": 3,
+    "browser": "chromium-1180",
+    "model_id": "claude-sonnet-4-6",
+    "temperature": 0
+  },
+  "transform": {
+    "dom_to_screen_scale": 1.0,
+    "safe_area_offset_pt": [0, 59],
+    "content_rect_pt": [0, 59, 393, 759],
+    "resample_filter": "lanczos3",
+    "color": "p3->srgb-relative"
+  },
+  "twin_hashes": {
+    "ref_png": "/abs/path/twin-ref.png",
+    "ref_sha256": "…64-hex…",
+    "gen_png": "/abs/path/twin-gen.png",
+    "gen_sha256": "…64-hex…"
+  },
+  "calibration_source": {
+    "h5_twin_dir": "assets/calibration/h5-twin",
+    "swiftui_twin_dir": "assets/calibration/swiftui-twin",
+    "h5_twin_source_sha256": "…64-hex…",
+    "swiftui_twin_source_sha256": "…64-hex…",
+    "source_tree_hash_algo": "sha256/sorted-relpath+filebytes/v1"
+  },
+  "floor": {
+    "ssim_global": 0.982,
+    "ssim_nontext": 0.991,
+    "deltaE_p95": 1.6,
+    "text_iou": null,
+    "luma_variance": { "ref": 612.4, "gen": 588.1, "flat_threshold": 9 }
+  },
+  "gate": {
+    "converged": {
+      "ssim_nontext_min": 0.986,
+      "deltaE_p95_max": 2.0,
+      "text_iou_min": null,
+      "require_judge_yes": true
+    },
+    "close": {
+      "ssim_nontext_min": 0.981,
+      "deltaE_p95_max": 2.4,
+      "text_iou_min": null,
+      "require_judge_equiv": true
+    },
+    "gate_explain": "human-readable only — code reads gate.converged / gate.close numerically"
+  },
+  "measured_at": "ISO8601"
+}
+```
+
+`gate.converged` / `gate.close` are **structured numeric objects**, not a
+string DSL — `scripts/evaluate-convergence.mjs` evaluates them directly
+without a parser (a legacy string gate is rejected as un-enforceable). They
+are derived from the measured floor: `ssim_nontext_min = floor − 0.005`,
+`deltaE_p95_max = floor + 0.4`, `text_iou_min = floor − 0.03` (null ⇒ the
+text-IoU sub-gate is skipped for that calibration); `close` is the 2× band.
+`gate_explain` is a human-only convenience string and is **never** evaluated
+by code. The numbers in `floor` are **measured per run**, not shipped
+constants — different Xcode/sim versions yield different floors, which is
+exactly why this stage exists. `floor.luma_variance` records each side's
+structure (a both-flat pair is blocked, never floored).
+
+### Provenance binding (enforced, not advisory)
+
+`scripts/evaluate-convergence.mjs` **mechanically binds** the floor it grades
+against — these are code-enforced fail-closed checks, not prose:
+
+1. **schema** — `calibration.json.schema` MUST be
+   `h5-to-swiftui/calibration@1`, else the grader exits 1 (it refuses to
+   grade against an unrecognized contract).
+2. **gate ⇐ floor** — the grader **recomputes** the expected structured gate
+   from `floor` with the published tolerances (converged
+   `ssim_nontext_min = floor − 0.005`, `deltaE_p95_max = floor + 0.4`,
+   `text_iou_min = floor − 0.03` when non-null; `close` = 2× band) and
+   rejects any `gate` that deviates beyond a 1e-4 rounding epsilon
+   (`gate-floor-mismatch`, exit 1). This binds the **gate to the floor**: a
+   hand-loosened `gate` (tight-looking `floor` + loose `gate`) is rejected
+   unless the `floor` itself is loosened. It does **not** bind the floor's
+   *value* — that is checks 3 and 4.
+3. **twin source identity ⇐ shipped twins** — `calibration_source` carries a
+   **deterministic SHA-256 source-tree hash** of the bundled
+   `assets/calibration/h5-twin` and `assets/calibration/swiftui-twin`
+   **source files (excluding build output/dotfiles)**. The grader
+   **recomputes those hashes from the actual shipped assets** (resolved
+   relative to the skill root, not the cwd) and fails closed
+   (`calibration-twin-mismatch`, exit 1) on any mismatch. This binds the
+   **identity of the bundled twin source files**. It does **not** re-measure
+   or bind the `floor` *value*: an attacker can keep the real, public,
+   unmodified bundled-twin source hashes here and still write a loose
+   `floor`. (The *rendered* PNGs are runtime-produced and not byte-stable
+   across machines, so the SOURCE tree — fixed and shippable — is what is
+   bound. `twin_hashes` is non-security provenance metadata of the exact PNGs
+   the floor was measured on; the *enforced* binding is the source-tree hash
+   of the source files.)
+4. **floor value ⇐ calibrate-render's own sanity envelope** — the grader
+   asserts `floor` satisfies the SAME sanity bound `calibrate-render.mjs`
+   enforces before it is willing to emit `calibration.json` at all
+   (`ssim_nontext ≥ 0.95`, non-null `text_iou ≥ 0.9`, metric-valid
+   `deltaE_p95`), via the shared `scripts/_calib-consts.mjs` (single source
+   of truth, imported by both producer and consumer). A `floor` that fails
+   this envelope could not have been produced by an honest
+   `calibrate-render.mjs` run (it writes `blocked.json`, not
+   `calibration.json`) ⇒ `floor-implausible`, exit 1. This **kills the
+   absurd-floor attack** (e.g. `ssim_nontext:0.05, deltaE_p95:200` with the
+   real public twin hashes copied in). It does **not** re-measure the floor:
+   a `floor` *within* this envelope yet looser than the TRUE measured floor
+   is still trusted — the grader cannot re-render the bundled twins to
+   re-derive the real number.
+
+**Named irreducible residuals (honest, per §1.1) — BOTH stated, neither
+hidden:**
+
+1. **The grader cannot re-execute the simulator renders.** It trusts the
+   per-iteration `pixel-diff.mjs` JSONs were produced by running the real
+   `pixel-diff.mjs` on real `sim-screenshot.sh` renders (bounded by that
+   script's no-fake build/env spine — no simulator / no build ⇒
+   `blocked`/`needs-human`, never converged).
+2. **The grader cannot re-measure the calibration floor.** Check 4 asserts
+   the supplied `floor` is within calibrate-render's own sanity envelope and
+   the gate is recomputed from it, but a `floor` *within* that envelope yet
+   looser than the true measured floor is trusted (the grader cannot
+   re-render the bundled twins to re-derive the real number). Mitigated by:
+   the orchestrator's contractual obligation to run the real,
+   sanity/flat-image-spined `calibrate-render.mjs`, and the human-readable
+   `calibration_provenance` recorded in the convergence artifact.
+
+Both residuals are irreducible without the grader itself re-rendering; they
+are stated, not hidden.
+
+## Reproducibility rule
+
+Re-running calibration on the same pinned toolchain must produce `floor`
+values within ±0.005 SSIM / ±0.3 ΔE. Larger drift ⇒ environment is unstable;
+record it and degrade the run's claims (Stage 5 verdicts become advisory).

package/.local/skills/h5-to-swiftui/references/stack-detection.md

@@ -0,0 +1,160 @@
+# Stack Detection — Stage 0
+
+Used by `scripts/detect-stack.mjs`. Runs **before any other stage**. Determines
+whether the project is in v1 scope; out-of-scope projects stop here with an
+explicit written report — they are never guessed past.
+
+---
+
+## Why native rewrite beats WebView shell and mechanical transpilation
+
+Condensed from findings.md RQ1 (sources: kean.blog; Apple "Composing custom
+layouts" WWDC22-10056; MDN Specificity; LogRocket / Yoga 3.0; dbushell; bjango;
+fatbobman; MDN animations; tonsky.me; Android→iOS pilot 2507.16037).
+
+| Route | Fidelity ceiling | Core failure mechanism |
+|---|---|---|
+| WebView shell (Capacitor / Cordova / Ionic) | ~70–80% | Renders in WebKit, not Core Animation/Metal; ProMotion 120 Hz unavailable to WebKit-rendered content; Dynamic Type needs full reload; rubber-band scroll constant diverges; haptics absent; 2 extra OS processes per instance |
+| React Native / NativeScript | ~85–92% | Yoga bridge drops 5 CSS flex properties (`flex-basis`, `flex` shorthand, `wrap-reverse`, `order`, column/row-gap individually); bridge latency; not SwiftUI semantics |
+| Flutter (Impeller) | ~80–85% | Own GPU renderer independent of UIKit; iOS conventions require manual Cupertino override throughout |
+| Mechanical transpilation (DOM→view tree) | **<60%** | Six structural incompatibilities listed below — errors compound per nesting level |
+| **Native rewrite** (this skill) | **100% platform ceiling** | Requires a render-measure-feedback loop; see `visual-diff-loop-protocol.md` |
+
+### Six reasons mechanical transpilation cannot reach pixel-level
+
+1. **Inverted layout protocol.** CSS: parent establishes a containing block;
+   child size = content + padding + border + margin. SwiftUI: parent _proposes_
+   a size; child _chooses_; parent must honor it. The information-flow direction
+   is reversed. Reconstructing it from CSS is underdetermined for nested
+   layouts. (kean.blog; Apple "Composing custom layouts".)
+
+2. **No cascade.** CSS resolves styles by global selector specificity +
+   inheritance + `!important`. SwiftUI styling is local modifier-chain order +
+   downward `environment`. A transpiler needs a full cascade engine; any cascade
+   error is a visible defect. (MDN Specificity.)
+
+3. **No 1:1 flex mapping.** Yoga (the most mature CSS-flex bridge) drops
+   `flex-basis`, the `flex` shorthand, `wrap-reverse`, `order`, and individual
+   `row-gap`/`column-gap`. Errors compound per nesting level. (LogRocket /
+   Yoga 3.0.)
+
+4. **Font metric divergence.** WebKit implements `line-height: normal ≈ 1.2`
+   against the CSS font spec; SwiftUI uses CoreText metrics directly. Identical
+   `16px` declarations yield different line height, advance width, and
+   baseline — different wrap column — all subsequent layout shifts. (dbushell;
+   bjango.)
+
+5. **Animation model mismatch.** CSS = timeline keyframes on absolute time;
+   SwiftUI = state-diff interpolation on Core Animation. Mechanical
+   `@keyframes` → `.animation()` diverges in timing, easing, and
+   interruptibility. (fatbobman; MDN animations.)
+
+6. **Non-deterministic adaptive spacing.** SwiftUI inserts type-dependent
+   spacing and context-sensitive control styling with no CSS source to
+   translate from. (tonsky.me.)
+
+**Takeaway:** native rewrite is the only route to the 100% ceiling; transpilation
+is at best a draft generator; a render-diff feedback loop is mandatory because
+these divergences are invisible to static code diffing.
+
+---
+
+## Detection heuristics table
+
+`detect-stack.mjs` reads `package.json` + a shallow source scan (`.js/.ts/.jsx/
+.tsx/.vue/.svelte` in `src/` or root, max 500 files). No network calls.
+
+### Framework detection
+
+| Framework | `package.json` deps (any of) | Source signatures |
+|---|---|---|
+| React | `react`, `react-dom`, `@types/react` | `import React`, `JSX.Element`, `.jsx`/`.tsx` extensions, `ReactDOM.render`, `createRoot` |
+| Vue | `vue`, `@vue/core`, `nuxt` | `.vue` files, `<template>` + `<script setup>`, `createApp` |
+| Svelte | `svelte`, `@sveltejs/kit` | `.svelte` files, `<script>` + `<style>` co-located, `$:` reactivity |
+| Angular | `@angular/core`, `@angular/common` | `@Component`, `@NgModule`, `.component.ts` suffix pattern |
+| Solid | `solid-js`, `@solidjs/router` | `createSignal`, `createEffect`, `.jsx` with no `react` dep |
+| Vanilla | none of the above in deps | Bare `addEventListener`, no framework imports, `.js`/`.ts` only |
+
+Confidence scoring: `high` = dep present + source signature found; `medium` =
+dep only (source scan inconclusive); `low` = source signature only (dep absent,
+e.g. CDN-loaded). At `low` confidence, `detect-stack.mjs` logs a warning and
+continues; `in_v1_scope` reflects the most-likely classification.
+
+### Build tool detection
+
+| Build tool | Primary signal | Secondary signal |
+|---|---|---|
+| Vite | `vite` in deps or devDeps; `vite.config.{js,ts}` present | `"dev": "vite"` in scripts |
+| webpack | `webpack` in deps; `webpack.config.{js,cjs,mjs}` present | `"build": "webpack"` in scripts |
+| Next.js | `next` in deps; `next.config.{js,mjs,ts}` present | `pages/` or `app/` dir with `page.{tsx,jsx}` |
+| Nuxt | `nuxt` in deps; `nuxt.config.{ts,js}` present | `pages/` dir with `.vue` files |
+| CRA | `react-scripts` in deps | `"start": "react-scripts start"` in scripts |
+| None | none of the above | Single `index.html` + inline `<script>` or `<script type=module>` |
+
+### Styling detection
+
+| Styling system | Detection signal |
+|---|---|
+| Tailwind v3 | `tailwindcss@^3` in deps; `tailwind.config.{js,ts}` present; class names like `text-sm`, `flex`, `bg-gray-100` in source |
+| Tailwind v4 | `tailwindcss@^4` in deps; `@import "tailwindcss"` or `@theme` block in a `.css` file; no `tailwind.config.*` |
+| CSS Modules | `.module.css` / `.module.scss` files present; `import styles from '…module.css'` in source |
+| Sass / SCSS | `.scss` or `.sass` files; `sass` or `node-sass` in deps |
+| CSS-in-JS | `styled-components`, `@emotion/react`, `@emotion/styled`, `@stitches/react`, or `linaria` in deps |
+| Plain CSS | None of the above; `.css` files imported directly |
+
+### Router detection
+
+| Router | Detection signal |
+|---|---|
+| React Router | `react-router-dom` or `react-router` in deps |
+| TanStack Router | `@tanstack/react-router` in deps |
+| Next.js router | Next.js detected (built-in) |
+| Vue Router | `vue-router` in deps |
+| Wouter | `wouter` in deps |
+| None | Single-page with no router dep |
+
+---
+
+## v1 scope gate
+
+**v1 supports: framework ∈ {vanilla, React}.**
+
+All other detected frameworks (Vue, Svelte, Angular, Solid) are **out of v1 scope**.
+`detect-stack.mjs` writes `stack-report.json` and **exits with code 2** (not 0,
+not 1 — pipeline scripts detect this as a scope-stop, not an error).
+
+The pipeline does **not** attempt to convert an out-of-scope project. It does not
+guess. It does not warn and continue. It stops cleanly so the caller knows exactly
+what happened.
+
+### `stack-report.json` schema
+
+```json
+{
+  "schema": "h5-to-swiftui/stack-report@1",
+  "framework": "vue",
+  "buildTool": "vite",
+  "styling": ["css-modules", "tailwind-v3"],
+  "router": "vue-router",
+  "confidence": "high",
+  "in_v1_scope": false,
+  "stop_reason": "detected=vue, out of v1 scope; v1 supports vanilla|React only",
+  "detected_at": "2026-05-19T12:00:00Z"
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `framework` | string | `vanilla` \| `react` \| `vue` \| `svelte` \| `angular` \| `solid` \| `unknown` |
+| `buildTool` | string | `vite` \| `webpack` \| `next` \| `nuxt` \| `cra` \| `none` \| `unknown` |
+| `styling` | string[] | Array; a project may use multiple (e.g. `["tailwind-v3","css-modules"]`) |
+| `router` | string | Primary detected router or `none` |
+| `confidence` | string | `high` \| `medium` \| `low` |
+| `in_v1_scope` | boolean | `true` only when `framework` is `vanilla` or `react` |
+| `stop_reason` | string | Present only when `in_v1_scope: false` |
+| `detected_at` | string | ISO-8601 timestamp |
+
+When `in_v1_scope: true`, the pipeline proceeds to Stage 1. The `stack-report.json`
+is retained as a Stage 0 artifact and its fields inform Stage 1 (token extraction
+strategy differs for plain CSS vs Tailwind v4 vs CSS-in-JS) and Stage 4 (component
+pattern differs for class components vs function+hooks vs vanilla DOM).