animate-my-app 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @oiharshit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# animate-my-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Claude Code skill that turns an app design into a **native, animated iOS app**, the kind of motion people post and ask "how did you make this?".
+
+Drop in a Figma link or screenshots and ask Claude to animate it. The skill makes Claude:
+
+- build a real SwiftUI app: layout, text, buttons, haptics and safe areas stay native;
+- render hero parts (logos, 3D objects, clay characters, paper, chrome, painted backgrounds) in a **three.js** layer, built procedurally rather than from cut-up images;
+- move things with **real physics**: damped springs, gravity, squash and stretch that keeps volume, contact shadows, and staging that waits for things to land;
+- load every texture and compile every shader **before** the clock starts, so nothing loads mid-animation;
+- **test what it builds**: Simulator recordings checked frame by frame, a frame-time probe (target: 0 frames over 25 ms), and an optional self-test on your iPhone;
+- ask you about the motion before guessing.
+
+## Install
+
+**Claude Code plugin (recommended)**
+
+```bash
+claude plugin marketplace add contactharshitdesign-design/animate-my-app
+```
+
+```bash
+claude plugin install animate-my-app@animate-my-app
+```
+
+Or inside Claude Code: `/plugin marketplace add contactharshitdesign-design/animate-my-app`, then `/plugin install animate-my-app@animate-my-app`.
+
+**npx (copies the skill into `~/.claude/skills`)**
+
+```bash
+npx animate-my-app
+```
+
+Add `--project` to install it into the current project's `.claude/skills` instead, and `--force` to replace an older copy (it's backed up first).
+
+## Use
+
+Ask Claude Code for any app motion, for example:
+
+- "Animate this onboarding from Figma: <link>"
+- "Make the splash logo drop in and squash like clay"
+- "The paper should fall onto page 2 with real physics"
+- "Turn this seat map into 3D and fly into the seat I tap"
+
+The skill scaffolds an app with `scripts/new_app.sh`, builds it, runs it in the Simulator and reports measured results.
+
+## Requirements
+
+- macOS with Xcode and an iOS Simulator runtime
+- Claude Code
+- Optional: an Apple developer team ID to run on your own iPhone; the Figma MCP server for Figma links
+
+## What's inside
+
+```
+skills/animate-my-app/
+├── SKILL.md            the workflow and the rules
+├── references/         craft guide, stack, motion physics, procedural 3D, testing, research and tools, lessons learned
+├── scripts/            new_app.sh scaffold, frame extraction, hitch probe, framed video, SF Symbol export
+└── assets/template/    a working SwiftUI + three.js app the scaffold copies
+```
+
+## Author
+
+Made by [@oiharshit](https://x.com/oiharshit).
+
+## License
+
+[MIT](LICENSE)

package/bin/install.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// npx animate-my-app            → installs the skill for you (~/.claude/skills/animate-my-app)
+// npx animate-my-app --project  → installs it into this project (./.claude/skills/animate-my-app)
+// add --force to replace an existing copy (the old one is kept as a timestamped backup)
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: npx animate-my-app [--project] [--force]');
+  process.exit(0);
+}
+const project = args.includes('--project');
+const force = args.includes('--force');
+const src = path.join(__dirname, '..', 'skills', 'animate-my-app');
+const root = project ? path.join(process.cwd(), '.claude', 'skills') : path.join(os.homedir(), '.claude', 'skills');
+const dest = path.join(root, 'animate-my-app');
+
+if (!fs.existsSync(path.join(src, 'SKILL.md'))) { console.error('animate-my-app: the packaged skill is missing.'); process.exit(1); }
+fs.mkdirSync(root, { recursive: true });
+if (fs.existsSync(dest)) {
+  if (!force) {
+    console.log(`animate-my-app is already installed at ${dest}\nRun again with --force to replace it (your current copy is backed up).`);
+    process.exit(0);
+  }
+  // backups live outside the skills folder, or Claude would load them as a second copy of the skill
+  const backups = path.join(os.homedir(), '.claude', 'skill-backups');
+  fs.mkdirSync(backups, { recursive: true });
+  const backup = path.join(backups, `animate-my-app-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+  fs.renameSync(dest, backup);
+  console.log(`Backed up the old copy to ${backup}`);
+}
+fs.cpSync(src, dest, { recursive: true });
+for (const f of ['new_app.sh']) {               // keep scripts executable
+  const p = path.join(dest, 'scripts', f);
+  if (fs.existsSync(p)) fs.chmodSync(p, 0o755);
+}
+console.log(`Installed animate-my-app → ${dest}`);
+console.log('Restart Claude Code (or run /reload-skills), then ask it to animate your app design.');

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "animate-my-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "A Claude Code skill: turn an app design into a native, animated iOS app (SwiftUI + three.js), tested on device. Run `npx animate-my-app` to install.",
+  "bin": {
+    "animate-my-app": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skill",
+    "animation",
+    "ios",
+    "swiftui",
+    "threejs"
+  ],
+  "author": "@oiharshit",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contactharshitdesign-design/animate-my-app.git"
+  },
+  "homepage": "https://github.com/contactharshitdesign-design/animate-my-app#readme"
+}

package/skills/animate-my-app/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: animate-my-app
+description: >
+  Turn an app design (Figma frames, screenshots, a reference video or an existing app) into a real, native,
+  animated iOS app that runs in the Simulator and on iPhone: SwiftUI for layout, text and buttons, plus a
+  transparent three.js/WebGL layer for hero motion (clay or chrome 3D objects, logos that assemble, shader and
+  paint backgrounds, page curls, particles, physics, gesture-driven 3D). Use it for any request to animate an
+  app design or screen; build or fix an onboarding, splash, intro, screen transition, logo or hero animation;
+  recreate motion from a reference (Dribbble, Pinterest, a video); tune how something moves (springs, squash and
+  stretch, gestures, swipes, card stacks, pull-to-refresh); or add three.js, shaders or physics to a native iOS
+  app. Ships a scaffold script, motion and procedural-3D recipes, measurement scripts for frame times and
+  motion, and a list of WKWebView, three.js, SwiftUI and Simulator gotchas.
+license: MIT
+metadata:
+  author: "@oiharshit"
+  version: "1.1.0"
+---
+
+# Animate My App
+
+Take a designed app screen (usually from Figma) and ship it as a native iOS app whose hero moments move like a
+Rive- or three.js-level piece: physical, staged, measured. Speed comes from **reusing this pipeline** (scaffold,
+engine, test scripts, recipes), not re-deriving it for every app.
+
+## 0. Before anything: read the craft guide
+
+Read `references/craft.md` at the start of every build. It sets the bar for motion, interaction, accessibility,
+visual polish, typography, colour and Figma-to-code fidelity, and ends with the review checklist to run before
+you report. This skill is self-contained: everything it needs is in this folder.
+
+## 1. Intake (fast), then ASK
+
+1. Pull every frame that was linked: Figma MCP `get_screenshot` + `get_design_context` + `get_metadata`
+   (+ `download_assets` for raster art, fonts, exact colours and sizes). Details and fallbacks:
+   `references/research-and-tools.md`.
+2. Find references when the motion idea is open: Mobbin (MCP or website), Pinterest, Dribbble, a supplied video.
+   Generated assets or motion references can come from an image/video generation service if one is connected.
+3. **Ask** (2–4 pointed questions) whenever the motion intent is not explicit: sequence and staging, feel (bouncy
+   clay / crisp / calm), total length, what is procedural vs image, sound or none, the hand-off between screens.
+   When motion is described in words, restate it as physics and confirm ("squeeze → stretch and move on the same
+   frame, tallest early in the climb?"). Ask again mid-build whenever a choice changes the result. Never guess
+   on intent that matters.
+
+## 2. Build: native app + three.js layer
+
+Scaffold in one command (working app, replay protocol, preload/warm-start engine, demo content):
+
+```bash
+scripts/new_app.sh <AppName> <parent-dir> [bundle.id]   # default bundle id: com.example.<appname>
+```
+
+Architecture, bridge and engine API: `references/stack.md`. In short:
+- SwiftUI owns layout, text, buttons, haptics, safe areas. A transparent full-screen `WKWebView` runs three.js
+  for hero parts, served over a custom scheme (WebGL refuses `file://` textures). Created eagerly at launch.
+- **One timeline** (JS) is the source of truth; it fires cues (`headline`, `button`, …) that SwiftUI animates.
+- Design canvas = the Figma frame in points (iPhone 17 Pro 402×874); ortho camera in design points.
+- Pick the right tool per part: three.js for 3D/clay/shaders/procedural paint; SwiftUI springs,
+  `matchedGeometryEffect`, `PhaseAnimator`/`KeyframeAnimator` for UI; Rive/Lottie only when such assets are
+  supplied or the part is pure 2D vector character animation.
+
+**Build hero parts procedurally, not from cut-up images.** Image cut-outs crack, fringe and flicker. Recipes for
+clay letters (SDF + surface nets + clay shader), chrome and metal, self-painting brush backgrounds, paper, and
+splitting illustrations into clean animatable pieces: `references/procedural-3d.md`. Photographed people with
+swappable pieces: `references/photo-layers.md`.
+
+## 3. Motion rules
+
+Full formulas and constants: `references/motion-physics.md`; timing, easing, gestures and polish:
+`references/craft.md`.
+- Real physics: damped springs (damping ratio + response), gravity drops, squash and stretch that **preserves
+  volume**, contact shadows that react to height.
+- Anticipation without dwell: squeeze, then stretch **and** move on the same frame; peak stretch early in the
+  travel; jelly follow-through; overshoot then a braking squash. Stretch must be clearly visible.
+- **Staging is gated on arrival**: the next phase starts only after the previous element has truly landed
+  (compute the arrival time, don't guess a delay).
+- Entrances never from `scale(0)`; press feedback 0.97 + light haptic; always a reduced-motion path.
+- Buttons and text match Figma exactly (measure size, radius, colour, inner glows) and sit per Apple HIG
+  (primary button 16 pt above the bottom safe area; keep the designed spacing to the headline).
+
+## 4. Hard rules (defaults)
+
+- **No clipping** unless asked or the Figma frame has "Clip content" on. Pad every bounded surface (planes,
+  textures, canvases, frames) so brush ends, shadows, glows and overshoot fit. Check every edge of rendered frames
+  for straight cuts before delivering. If source art itself is cut, repair it.
+- **No mid-animation loading:** decode + GPU-upload every texture and pre-warm every shader *before* the clock
+  starts; warm frames before the first move. Measure; target 0 frames > 25 ms on replay.
+- **Replay protocol:** every app listens for the Darwin notification `com.animatemyapp.replay` and replays its
+  intro in place (fade to white → reset → warm → start), plus tap-to-replay outside buttons. Never relaunch to replay.
+- Real native app in the Simulator (and on iPhone), never a localhost/web demo. Status bar 9:41 for anything shown.
+- **Concentric corners:** outer radius = inner radius + padding for every nested rounded shape (thumbnail in a
+  card, highlight in a menu, chip in a composer, outline around media). Derive radii from the innermost element
+  out; break it only when truly necessary (full-bleed media clipped by its card simply inherits the card radius).
+- No sound unless asked.
+- **Test everything** yourself before reporting (section 5). Report measured numbers, not impressions.
+
+## 5. Verify
+
+`references/testing.md` has the scripts and checks. Minimum every iteration:
+1. Build (iOS Simulator build tool if available, else `xcodebuild`), install, launch on a simulator you booted
+   (pass its UDID to every `simctl` call).
+2. Record (`xcrun simctl io <UDID> recordVideo`), extract frames (`scripts/frames.swift`), and check the
+   sequence numerically: timing order, stretch amounts, overshoot, arrival before next phase, no cuts at edges.
+3. Frame-time probe in-app for stalls (snippet in testing.md); replay via the notification and confirm 0 stalls.
+   Simulator WebGL is software-rendered and noisy under load: judge performance on a real iPhone when one is available.
+4. Look at contact sheets yourself; compare against the Figma screenshot.
+
+## 6. Deliver
+
+- **Recording:** override the status bar to 9:41, warm-launch once, then trigger the in-place replay
+  (`xcrun simctl spawn <UDID> notifyutil -p com.animatemyapp.replay`) while recording with
+  `xcrun simctl io <UDID> recordVideo`, or with your own screen recorder. Don't record unless asked.
+- **Framed video** when asked: `scripts/frame_video.swift` (iPhone frame on white, ≥ 120 px margins, 60 fps).
+- **Side-by-side with a reference:** `scripts/side_by_side.swift`.
+- Gotchas that cost time before: `references/gotchas.md`. Read it once per build.
+
+## 7. Keep this skill growing
+
+After each app, add what was learned (new recipe, new gotcha, a measured constant) to the matching reference
+file, written as general guidance, so the next build is faster.

package/skills/animate-my-app/assets/template/__APP__/App.swift

@@ -0,0 +1,38 @@
+import SwiftUI
+import CoreText
+
+@main
+struct __APP__App: App {
+    init() {
+        Self.registerFonts()
+        _ = SceneBridge.shared       // start the scene's web process now, in parallel with launch
+        Self.listenForReplay()
+    }
+
+    /// Registers every font file bundled with the app (drop .ttf/.otf anywhere in the app folder).
+    /// Use the font's PostScript name in `.font(.custom(...))`.
+    static func registerFonts() {
+        for ext in ["ttf", "otf", "ttc"] {
+            for url in Bundle.main.urls(forResourcesWithExtension: ext, subdirectory: nil) ?? [] {
+                CTFontManagerRegisterFontsForURL(url as CFURL, .process, nil)
+            }
+        }
+    }
+
+    /// `xcrun simctl spawn booted notifyutil -p com.animatemyapp.replay` (or any tool posting that Darwin notification) replays the intro in place.
+    static func listenForReplay() {
+        CFNotificationCenterAddObserver(CFNotificationCenterGetDarwinNotifyCenter(), nil, { _, _, _, _, _ in
+            DispatchQueue.main.async { NotificationCenter.default.post(name: .replayRequested, object: nil) }
+        }, "com.animatemyapp.replay" as CFString, nil, .deliverImmediately)
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+
+extension Notification.Name {
+    static let replayRequested = Notification.Name("com.animatemyapp.replay")
+}

package/skills/animate-my-app/assets/template/__APP__/Assets.xcassets/Contents.json

@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}

package/skills/animate-my-app/assets/template/__APP__/ContentView.swift

@@ -0,0 +1,123 @@
+import SwiftUI
+
+/// Laid out on the Figma canvas in points and scaled to the device. The three.js timeline is the single
+/// source of truth: it sends cues ("headline", "button", …) and SwiftUI animates the native UI on them.
+struct ContentView: View {
+
+    // Design canvas = the Figma frame (iPhone 17 Pro logical size).
+    private let CW: CGFloat = 402
+    private let CH: CGFloat = 874
+
+    private let bridge = SceneBridge.shared
+    @State private var headIn = false
+    @State private var btnIn = false
+    @State private var veil = false        // content fades to white while a replay resets behind it
+    @State private var replaying = false
+
+    private let brand = Color(red: 8 / 255, green: 118 / 255, blue: 255 / 255)
+    private let ink = Color(red: 26 / 255, green: 26 / 255, blue: 26 / 255)
+
+    /// Primary action sits in the thumb zone: 16pt above the bottom safe area (Apple HIG), never in the
+    /// home-indicator area. Keep the designed spacing between headline and button.
+    private let buttonGapAboveSafeArea: CGFloat = 16
+
+    private var bottomSafeInset: CGFloat {
+        UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .flatMap { $0.windows }
+            .first { $0.isKeyWindow }?.safeAreaInsets.bottom ?? 34
+    }
+
+    var body: some View {
+        GeometryReader { geo in
+            let s = min(geo.size.width / CW, geo.size.height / CH)
+            ZStack {
+                Color.white
+
+                SceneLayer(bridge: bridge)
+                    .frame(width: CW, height: CH)
+                    .allowsHitTesting(false)
+                    .opacity(veil ? 0 : 1)
+
+                // tap anywhere (except the button) to replay; the web view would otherwise swallow touches
+                Color.clear
+                    .contentShape(Rectangle())
+                    .onTapGesture { replay() }
+
+                VStack(spacing: 32) {
+                    Text("Replace with the design's headline")
+                        .font(.system(size: 34, weight: .bold))
+                        .multilineTextAlignment(.center)
+                        .foregroundColor(ink)
+                        .frame(width: 360)
+                        .allowsHitTesting(false)
+                        .opacity(headIn ? 1 : 0)
+                        .offset(y: headIn ? 0 : 26)
+
+                    Button {
+                        UIImpactFeedbackGenerator(style: .light).impactOccurred()
+                    } label: {
+                        Text("Get started")
+                            .font(.system(size: 16, weight: .bold))
+                            .foregroundColor(.white)
+                            .frame(width: 354, height: 58)
+                            .background(Capsule().fill(brand))
+                    }
+                    .buttonStyle(PressScaleStyle())
+                    .allowsHitTesting(btnIn)
+                    .opacity(btnIn ? 1 : 0)
+                    .offset(y: btnIn ? 0 : 26)
+                    .scaleEffect(btnIn ? 1 : 0.9)
+                }
+                .padding(.bottom, bottomSafeInset / s + buttonGapAboveSafeArea)
+                .frame(width: CW, height: CH, alignment: .bottom)
+                .opacity(veil ? 0 : 1)
+            }
+            .frame(width: CW, height: CH)
+            .scaleEffect(s)
+            .position(x: geo.size.width / 2, y: geo.size.height / 2)
+        }
+        .ignoresSafeArea()
+        .background(Color.white.ignoresSafeArea())
+        .onReceive(NotificationCenter.default.publisher(for: .replayRequested)) { _ in replay() }
+        .onAppear {
+            bridge.onEvent = { event in
+                switch event {
+                case "headline": withAnimation(.spring(response: 0.5, dampingFraction: 0.8)) { headIn = true }
+                case "button": withAnimation(.spring(response: 0.5, dampingFraction: 0.7)) { btnIn = true }
+                case "reset" where replaying:
+                    // the scene is blank again; lift the veil a beat later so no old frame can show
+                    DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
+                        withTransaction(Transaction(animation: nil)) { veil = false }
+                        replaying = false
+                    }
+                default: break
+                }
+            }
+        }
+    }
+
+    /// Restart the intro from its first frame: fade to white, reset behind the veil, start warm.
+    private func replay() {
+        guard !replaying else { return }
+        replaying = true
+        withAnimation(.easeOut(duration: 0.18)) { veil = true }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
+            withTransaction(Transaction(animation: nil)) {
+                headIn = false
+                btnIn = false
+            }
+            bridge.replay()
+        }
+    }
+}
+
+/// Pressables acknowledge the touch immediately: a quick 0.97 scale-down, released with a soft spring.
+private struct PressScaleStyle: ButtonStyle {
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .scaleEffect(configuration.isPressed ? 0.97 : 1)
+            .animation(configuration.isPressed ? .easeOut(duration: 0.1) : .spring(response: 0.3, dampingFraction: 0.6),
+                       value: configuration.isPressed)
+    }
+}

package/skills/animate-my-app/assets/template/__APP__/SceneBridge.swift

@@ -0,0 +1,88 @@
+import SwiftUI
+import WebKit
+
+/// Serves bundled files over `appbundle://` so every file (scripts, textures) is same-origin —
+/// WebGL refuses textures loaded from `file://` URLs.
+final class BundleSchemeHandler: NSObject, WKURLSchemeHandler {
+    static let scheme = "appbundle"
+
+    func webView(_ webView: WKWebView, start task: WKURLSchemeTask) {
+        guard let url = task.request.url,
+              let file = Bundle.main.url(forResource: url.lastPathComponent, withExtension: nil),
+              let data = try? Data(contentsOf: file) else {
+            task.didFailWithError(URLError(.fileDoesNotExist))
+            return
+        }
+        let mime: String
+        switch file.pathExtension.lowercased() {
+        case "html": mime = "text/html; charset=utf-8"
+        case "js": mime = "text/javascript; charset=utf-8"
+        case "json": mime = "application/json"
+        case "png": mime = "image/png"
+        case "jpg", "jpeg": mime = "image/jpeg"
+        case "webp": mime = "image/webp"
+        case "glb": mime = "model/gltf-binary"
+        default: mime = "application/octet-stream"
+        }
+        let response = HTTPURLResponse(url: url, statusCode: 200, httpVersion: "HTTP/1.1",
+                                       headerFields: ["Content-Type": mime, "Content-Length": "\(data.count)",
+                                                      "Cache-Control": "no-store"])!   // never a stale script after a reinstall
+        task.didReceive(response)
+        task.didReceive(data)
+        task.didFinish()
+    }
+
+    func webView(_ webView: WKWebView, stop task: WKURLSchemeTask) {}
+}
+
+/// Owns the WKWebView that renders the three.js scene and bridges its timeline cues to SwiftUI.
+/// Created eagerly at app launch so the web process spins up in parallel with the app.
+final class SceneBridge: NSObject, WKScriptMessageHandler {
+    static let shared = SceneBridge()
+
+    let webView: WKWebView
+    var onEvent: ((String) -> Void)?
+
+    private override init() {
+        let config = WKWebViewConfiguration()
+        config.websiteDataStore = .nonPersistent()                  // no disk cache between launches
+        config.setURLSchemeHandler(BundleSchemeHandler(), forURLScheme: BundleSchemeHandler.scheme)
+        webView = WKWebView(frame: CGRect(x: 0, y: 0, width: 402, height: 874), configuration: config)
+        super.init()
+        config.userContentController.add(self, name: "scene")
+
+        webView.isOpaque = false
+        webView.backgroundColor = .clear
+        webView.scrollView.backgroundColor = .clear
+        webView.scrollView.isScrollEnabled = false
+        webView.scrollView.contentInsetAdjustmentBehavior = .never
+        webView.isUserInteractionEnabled = false
+        #if DEBUG
+        if #available(iOS 16.4, *) { webView.isInspectable = true }
+        #endif
+
+        // look-dev / test flags: SIMCTL_CHILD_SCENE_QUERY="perf&debug" xcrun simctl launch booted <bundle id>
+        let query = ProcessInfo.processInfo.environment["SCENE_QUERY"].map { "?\($0)" } ?? ""
+        if let url = URL(string: "\(BundleSchemeHandler.scheme)://app/scene.html\(query)") {
+            webView.load(URLRequest(url: url))
+        }
+    }
+
+    func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard let event = message.body as? String else { return }
+        if event.hasPrefix("perf:") { NSLog("[scene] %@", event); return }   // frame-time probe (?perf)
+        onEvent?(event)
+    }
+
+    func replay() {
+        webView.evaluateJavaScript("window.scenePlay && window.scenePlay()")
+    }
+}
+
+/// Transparent, non-interactive layer that shows the three.js scene above the native background.
+struct SceneLayer: UIViewRepresentable {
+    let bridge: SceneBridge
+
+    func makeUIView(context: Context) -> WKWebView { bridge.webView }
+    func updateUIView(_ webView: WKWebView, context: Context) {}
+}

package/skills/animate-my-app/assets/template/__APP__/Web/content.js

@@ -0,0 +1,53 @@
+// Demo part — replace with the design's hero animation. Shows the patterns every part follows:
+// state is a pure function of t (so replays are identical), physics via springs, volume-preserving squash,
+// a contact shadow that reacts to height, and cues that bring in the native UI.
+(function () {
+  'use strict';
+  const S = window.SCENE;
+  if (!S) return;
+  const { THREE, scene, toWorld, spring, k, REDUCED } = S;
+
+  // a soft clay pill (replace with procedural geometry built for the design)
+  const body = new THREE.Mesh(
+    new THREE.CapsuleGeometry(34 * k, 60 * k, 12, 32),
+    new THREE.MeshPhysicalMaterial({ color: 0xF6BE2C, roughness: 0.55, sheen: 0.35, sheenColor: 0xffffff }));
+  body.rotation.z = Math.PI / 2;
+  const pivot = new THREE.Group();                 // pivot at the object's base, so squash stays grounded
+  body.position.y = 34 * k;
+  pivot.add(body);
+  scene.add(pivot);
+
+  // contact shadow: radial-gradient blob on the ground
+  const c = document.createElement('canvas'); c.width = c.height = 128;
+  const g = c.getContext('2d'), gr = g.createRadialGradient(64, 64, 0, 64, 64, 64);
+  gr.addColorStop(0, 'rgba(255,255,255,1)'); gr.addColorStop(0.45, 'rgba(255,255,255,0.4)'); gr.addColorStop(1, 'rgba(255,255,255,0)');
+  g.fillStyle = gr; g.fillRect(0, 0, 128, 128);
+  const shadow = new THREE.Mesh(new THREE.PlaneGeometry(1, 1),
+    new THREE.MeshBasicMaterial({ map: new THREE.CanvasTexture(c), color: 0x2a1e14, transparent: true, depthWrite: false, opacity: 0 }));
+  shadow.renderOrder = -1;
+  scene.add(shadow);
+
+  const GROUND = toWorld(201, 470), T0 = 80, FALL = 0.32, DROP = 260 * k;
+  S.track((t) => {
+    const s = (t - T0) / 1000;
+    if (s < 0) { pivot.visible = shadow.visible = false; return; }
+    pivot.visible = shadow.visible = true;
+    let y = 0, sy = 1;
+    if (REDUCED) { y = 0; }
+    else if (s < FALL) { const u = s / FALL; y = DROP * (1 - u * u); sy = 1 + 0.18 * u; }   // gravity, stretched by speed
+    else { const tl = s - FALL; y = spring(0, 260 * k, 0.5, 0.32, tl); sy = 1 + spring(-0.22, -8, 0.42, 0.3, tl); }  // squash + hop
+    const sx = 1 / Math.sqrt(Math.max(sy, 0.3));   // keep the clay's volume
+    pivot.position.set(GROUND.x, GROUND.y + Math.max(0, y), 0);
+    pivot.scale.set(sx, sy, sx);
+    const h = Math.max(0, y) / (100 * k);
+    shadow.position.set(GROUND.x, GROUND.y - 2 * k, -10);
+    shadow.scale.set(150 * k * sx * (1 + 0.4 * h), 34 * k * (1 + 0.3 * h), 1);
+    shadow.material.opacity = 0.3 * Math.exp(-1.2 * h) * Math.min(1, s / 0.1);
+  });
+
+  // native UI comes in after the hero has landed (staging gated on arrival)
+  S.cue(T0 + FALL * 1000 + 450, 'headline');
+  S.cue(T0 + FALL * 1000 + 600, 'button');
+
+  // Textures for real parts: const tex = S.loadTexture('my-art.png');  (on the GPU before the clock starts)
+})();

package/skills/animate-my-app/assets/template/__APP__/Web/scene.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">
+<style>
+  html, body { margin: 0; height: 100%; overflow: hidden; background: transparent; }
+  canvas { display: block; }
+</style>
+</head>
+<body>
+<script>
+  // ?debug shows script errors on screen (look-dev in the simulator's Safari inspector also works)
+  if (location.search.indexOf('debug') !== -1) {
+    window.onerror = function (m, s, l, c, e) {
+      var p = document.createElement('pre');
+      p.style.cssText = 'position:fixed;top:60px;left:8px;right:8px;font:11px monospace;color:#c00;white-space:pre-wrap;z-index:9';
+      p.textContent = m + ' @' + l + ':' + c + '\n' + (e && e.stack || '');
+      document.body.appendChild(p);
+    };
+  }
+</script>
+<script src="three.min.js"></script>
+<!-- engine first, then one script per animated part -->
+<script src="scene.js"></script>
+<script src="content.js"></script>
+</body>
+</html>