lecodes-cli 2.4.2 → 2.4.3

package/src/commands/app/templates/ios.ts

@@ -636,6 +636,69 @@ export const LAUNCH_STORYBOARD = `<?xml version="1.0" encoding="UTF-8" standalon
 </document>
 `
 
+/** App/Base.lproj/LaunchScreen.storyboard as sync writes it when app.json sets "splash" (the file
+ *  is CLI-owned then; without the key it stays the person's, LAUNCH_STORYBOARD of init): the view's
+ *  colour is the colorset LeCodesSplashBackground, the image — when there is one — a size×size pt
+ *  UIImageView (aspect fit; "splash.size", 160 by default) of the imageset LeCodesSplash centred on
+ *  the view. Both live in Assets.xcassets, which
+ *  the project already compiles, so no pbxproj edit. `rgb` (0xRRGGBB) only feeds the storyboard's
+ *  resource cache (Interface Builder's preview); the app reads the colorset. LeCodesShellViewController
+ *  mounts this same storyboard over its container until the first frame. */
+export const splashStoryboardTemplate = (image: boolean, rgb: number, size = 160): string => {
+  const channel = (shift: number) => String(((rgb >> shift) & 0xff) / 255)
+  // The frame is Interface Builder's preview on its 375×667 canvas; the constraints place the view.
+  const x = (375 - size) / 2, y = (667 - size) / 2
+  const imageView = image ? `
+                        <subviews>
+                            <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleAspectFit" horizontalHuggingPriority="251" verticalHuggingPriority="251" image="LeCodesSplash" translatesAutoresizingMaskIntoConstraints="NO" id="LcS-im-001">
+                                <rect key="frame" x="${x}" y="${y}" width="${size}" height="${size}"/>
+                                <constraints>
+                                    <constraint firstAttribute="width" constant="${size}" id="LcS-cw-001"/>
+                                    <constraint firstAttribute="height" constant="${size}" id="LcS-ch-001"/>
+                                </constraints>
+                            </imageView>
+                        </subviews>` : ""
+  const centre = image ? `
+                        <constraints>
+                            <constraint firstItem="LcS-im-001" firstAttribute="centerX" secondItem="Ze5-6b-2t3" secondAttribute="centerX" id="LcS-cx-001"/>
+                            <constraint firstItem="LcS-im-001" firstAttribute="centerY" secondItem="Ze5-6b-2t3" secondAttribute="centerY" id="LcS-cy-001"/>
+                        </constraints>` : ""
+  return `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Generated by \`lecodes app sync\` from app.json "splash" — regenerated on every sync, do not edit. -->
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="13122.16" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
+    <dependencies>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="13104.12"/>
+        <capability name="Named colors" minToolsVersion="9.0"/>
+        <capability name="Safe area layout guides" minToolsVersion="9.0"/>
+        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
+    </dependencies>
+    <scenes>
+        <!--View Controller-->
+        <scene sceneID="EHf-IW-A2E">
+            <objects>
+                <viewController id="01J-lp-oVM" sceneMemberID="viewController">
+                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
+                        <rect key="frame" x="0.0" y="0.0" width="375" height="667"/>
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>${imageView}
+                        <viewLayoutGuide key="safeArea" id="6Tk-OE-BBY"/>
+                        <color key="backgroundColor" name="LeCodesSplashBackground"/>${centre}
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="53" y="375"/>
+        </scene>
+    </scenes>
+    <resources>${image ? `
+        <image name="LeCodesSplash" width="${size}" height="${size}"/>` : ""}
+        <namedColor name="LeCodesSplashBackground">
+            <color red="${channel(16)}" green="${channel(8)}" blue="${channel(0)}" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>
+        </namedColor>
+    </resources>
+</document>
+`
+}
+
 export const ASSETS_ROOT_JSON = `{
   "info" : {
     "author" : "xcode",
@@ -703,8 +766,16 @@ export interface RuntimePlugin {
   id: string
   /** Swift packages the target links (manifest ios.packages). */
   packages?: IosPackage[]
+  /** The binary targets the target links (manifest ios.binaries), by name: the xcframeworks sync
+   *  copies to `runtimeBinaryPath(id, name)`. */
+  binaries?: string[]
 }
 
+/** Where sync copies a plugin's prebuilt xcframework (manifest ios.binaries), relative to the
+ *  LeCodesRuntime package: inside it, as SwiftPM takes a binary target's path, beside the vendored
+ *  sources and with the same lifecycle (replaced on every sync, removed with the plugin). */
+export const runtimeBinaryPath = (id: string, name: string): string => `Binaries/${id}/${name}.xcframework`
+
 /** The SDK's engine variants — one tag of lecodes-ios-sdk per variant (`<version>` = full,
  *  `<version>-3d`, `-2d`, `-core`): core = UI only, 2d = + the 2D engine, 3d = + Filament with Jolt,
  *  full = everything. The Swift sources are the same; the engine binary differs. */
@@ -722,8 +793,9 @@ export const sdkProducts = (variant: SdkVariant): string[] =>
 /** LeCodesRuntime/Package.swift — the CLI-owned dependency graph: the SDK (one tag per
  *  variant, pinned with `.exact(…)`: the variant is the engine binary the tag's manifest names,
  *  so SwiftPM must never drift on its own — moving the version is the CLI's job, `lecodes app
- *  update` or app.json ios.sdk) + one vendored target per installed plugin. The SDK's assets
- *  (the 3D variants' shader archives) ride inside the package. */
+ *  update` or app.json ios.sdk) + one vendored target per installed plugin, + a binary target per
+ *  xcframework a plugin carries (its copy under Binaries/<id>/). The SDK's assets (the 3D variants'
+ *  shader archives) ride inside the package. */
 export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant, plugins: RuntimePlugin[], sdkPath?: string): string => {
   const sdkDep = (name: string) => `.product(name: "${name}", package: "lecodes-ios-sdk")`
   // LECODES_IOS_SDK_PATH: the SDK-development loop — a package tree on disk (release-ios-sdk.sh
@@ -746,18 +818,31 @@ export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant,
   }
   const packageDecls = [...packages.values()].map(pkg =>
     `\n        .package(url: "${pkg.url}", ${pkg.exact ? `exact: "${pkg.exact}"` : `from: "${pkg.from}"`}),`).join("")
+  // The plugins' prebuilt xcframeworks (manifest ios.binaries): a binary target each, by its copy's
+  // path. A name is one target of the package — two plugins carrying one alike cannot both link.
+  const targetNames = new Map<string, string>([["LeCodesRuntime", "the runtime's own target"], ...plugins.map(p => [p.module, `the module of "${p.id}"`] as [string, string])])
+  for (const p of plugins) {
+    for (const name of p.binaries ?? []) {
+      const prior = targetNames.get(name)
+      if (prior) throw new Error(`Plugin "${p.id}" carries the binary ${name} and ${name} is ${prior} — one name is one target of the shell's package.`)
+      targetNames.set(name, `a binary of "${p.id}"`)
+    }
+  }
   const pluginTargets = plugins.map(p => {
     const deps = [
       sdkDep("LeCodes"),
       ...(p.packages ?? []).flatMap(pkg => pkg.products.map(name => `.product(name: "${name}", package: "${swiftPackageName(pkg.url)}")`)),
+      ...(p.binaries ?? []).map(name => `"${name}"`),
     ]
+    const binaries = (p.binaries ?? []).map(name => `
+        .binaryTarget(name: "${name}", path: "${runtimeBinaryPath(p.id, name)}"),`).join("")
     return `
         // plugin: ${p.id} (vendored — see plugins.lock.json)
         .target(
             name: "${p.module}",
             dependencies: [${deps.join(", ")}],
             path: "Sources/${p.module}"
-        ),`
+        ),${binaries}`
   }).join("")
   const runtimeDeps = [...sdkProducts(variant).map(sdkDep), ...plugins.map(p => `"${p.module}"`)]
   return `// swift-tools-version:5.9
@@ -877,7 +962,7 @@ Yours — \`lecodes app sync\` never touches these:
   ≥1024px image and every sync renders AppIcon.png from it (flattened over \`"iconBackground"\`,
   default white — App Store icons must be opaque). Or leave the key unset and drop a
   1024×1024 PNG into AppIcon.appiconset/ yourself — sync never touches it then.
-- \`App/Base.lproj/LaunchScreen.storyboard\`
+- \`App/Base.lproj/LaunchScreen.storyboard\` — unless \`app.json\` sets \`"splash"\` (below)
 
 CLI-owned — regenerated on every sync, hand edits are overwritten:
 
@@ -888,10 +973,18 @@ CLI-owned — regenerated on every sync, hand edits are overwritten:
 - \`App/App.entitlements\` — the capabilities the installed plugins declare (e.g. push)
 - \`LeCodesRuntime/\` — local Swift package: the lecodes-ios-sdk dependency (one tag per engine
   variant), vendored plugin sources (Sources/<Module>/), and LeCodesAppViewController — the SDK's
-  shell controller with this project's plugins registered (App/ViewController.swift subclasses it)
+  shell controller with this project's plugins registered (App/ViewController.swift subclasses it).
+  A plugin's prebuilt xcframeworks (its manifest's \`ios.binaries\`) are copied to
+  Binaries/<plugin id>/: binary targets its vendored target links
 - the version values inside \`App.xcodeproj/project.pbxproj\` (from app.json)
 - this README
 
+CLI-owned **only when** \`../app.json\` sets \`"splash"\` — regenerated on every sync then;
+without the key sync never touches them (see "Splash screen"):
+
+- \`App/Base.lproj/LaunchScreen.storyboard\`
+- \`App/Assets.xcassets/LeCodesSplashBackground.colorset/\`, \`App/Assets.xcassets/LeCodesSplash.imageset/\`
+
 ## SDK variant
 
 Sync pins the SDK tag of the smallest engine variant that covers what the compiled bundle actually
@@ -900,30 +993,48 @@ physics, ~10 MB heavier), or \`full\` (everything) — \`<version>-core\`, \`-2d
 bare \`<version>\` for full. Adding your first 3D scene or 2D game to the project switches it
 automatically on the next sync; set \`ios.variant\` in \`../app.json\` to pin one instead.
 
+## Splash screen
+
+\`"splash": { "background": "#RRGGBB", "image": "./splash.png", "size": 160 }\` in \`../app.json\`
+(every key optional) makes every sync write the launch screen: a full-screen view of the colour
+(\`background\`, default \`"iconBackground"\`, default white) with the image fitted centred into a
+\`size\`×\`size\` pt square (160 by default) — never at its pixel size — from @1x/@2x/@3x renderings
+(size × 1/2/3 px: 160/320/480 at the default) of the one master. Use a square mark of at least
+3 × size px (a non-square one is fitted into the square, a smaller one is upscaled); the same key
+draws the Android splash, which crops the mark to a circle on Android 12+ — above a \`size\` of 192
+its corners are cut there (sync warns; 288 is the most it takes). No image = the colour alone. The app holds this screen until its first frame — through the
+first-launch wait of an OTA shell too — so nothing flashes between the two. iOS caches launch
+screens: after a change, delete the app from the device (or restart the device) to see the new one.
+
 ## Over-the-air updates
 
 With \`"update": true\` in \`../app.json\` (server-backed projects; or
 \`"update": {"url": "https://…/app.js"}\` for any static hosting), the app checks that URL
 at launch — natively, before any JS runs, so a broken bundle can never block its own fix.
-Unchanged code costs a ~0-byte 304; new code downloads in the background and runs on the
-NEXT launch. Offline it's a silent no-op — the app always launches from a local bundle.
-An App Store update always beats a cached OTA bundle. JS only: adding/removing native
-plugins still needs a store release.
+Unchanged code costs a ~0-byte 304. The FIRST launch of an installed build waits for the answer
+(5 s at most, the launch screen held on screen) and runs the newest bundle at once, so a fresh
+install from the App Store never starts on the older code it shipped with; every later launch
+runs the local bundle at once, new code downloads in the background and runs on the NEXT launch.
+Offline it's a silent no-op with no wait — the app always launches from a local bundle. An App
+Store update keeps a downloaded bundle only when it is newer code than the one the update ships
+(by compile date); otherwise the store build wins. JS only: adding/removing native plugins still
+needs a store release.
 
 Shipping an update is just \`lecodes push --publish\` — no rebuild, no store review:
 running apps download the new code on their next launch and run it on the launch after.
 
 Shells generated before OTA support have a \`ViewController.swift\` that reads app.js from
 \`Bundle.main\` directly, so downloaded updates would never run — and since \`App/*.swift\`
-is yours, sync won't rewrite it (\`lecodes app doctor\` flags this). Replace the
-\`Bundle.main\` load with:
+is yours, sync won't rewrite it (\`lecodes app doctor\` flags this). Make it subclass
+\`LeCodesAppViewController\` (the boot above, the first-launch wait included), or replace the
+\`Bundle.main\` load with (no wait):
 
 \`\`\`swift
-LeCodesUpdater.checkForUpdate()
 guard let code = LeCodesUpdater.activeBundle() else {
     print("LeCodes: bundled app.js is missing — run \`lecodes app sync\`")
     return
 }
+LeCodesUpdater.checkForUpdate()
 engine.run(code)
 \`\`\`
 

package/src/commands/init/index.ts

@@ -1,195 +1,195 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs"
-import { basename, dirname, join, resolve } from "node:path"
-import { LECODES_DIR } from "../../project/manifest"
-import { materializeTypesLocal, writeTsconfig } from "../../project/types"
-import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../../project/ignore"
-import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./templates"
-import { bool, c, defineCommand, log, note, success, warnErr } from "../../cli"
-
-/*
- * `lecodes init [dir]` — scaffold a brand-new LOCAL project: no account, no login, no server.
- *
- * Writes a starter entry, a CLAUDE.md (the headless render/test workflow for AI assistants) with
- * a passing starter flow test, the SDK's import-free type surface + a tsconfig (so VS Code gives
- * full IntelliSense offline), and a `.lecodesignore`. The result runs immediately with `lecodes dev`
- * (hot reload on a device) and compiles with `lecodes compile -o app.js` (a self-contained bundle
- * for LeCodes Desktop). It's the offline counterpart to `lecodes create`, which makes a project on
- * the server; a local project needs no manifest — `dev`/`compile` compile straight from the tree.
- *
- * Idempotent: existing files are kept (never clobbered), so it's safe to re-run or run in a folder
- * that already has content. Only the generated tsconfig + `.lecodes/types/` are rewritten each run.
- */
-
-const STARTER = `// Welcome to LeCodes — the whole SDK is available as globals, no imports needed.
-// Run it live on a device with \`lecodes dev\`, or bundle it with \`lecodes compile -o app.js\`.
-
-let count = 0
-
-const counter = UIText("Taps: 0").style({ color: "#9fb0d0", fontSize: 22, marginTop: 18 })
-
-const button = UIButton(UIText("Tap me").style({ color: "#ffffff", fontSize: 22 }))
-  .style({
-    backgroundColor: "#4f7cff",
-    borderRadius: 14,
-    paddingVertical: 16,
-    paddingHorizontal: 40,
-    marginTop: 24,
-    alignItems: "center",
-    justifyContent: "center",
-    $hovered: { backgroundColor: "#6b91ff" }, // the mouse over it (desktop); $pressed is the press
-  })
-  .named("tap") // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
-  .onClick(() => {
-    count++
-    counter.text = "Taps: " + count
-  })
-
-const screen = UIScreen(
-  UIColumn(UIText("Hello, LeCodes").style({ color: "#ffffff", fontSize: 32 }), button, counter)
-    .style({ backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" }),
-)
-  .style({ backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 })
-  .named("home") // the screen root's name is what tests' \`expect: { screen: … }\` reads
-
-screen.open()
-`
-
-/** `--desktop`: declare the desktop target up front. Window sizes are logical units (the host
- *  scales for HiDPI); `dev --desktop` / `desktop run` / `render --desktop` all read this, and a
- *  desktop-only app.json makes headless render/test default to the window size too. */
-const appJsonDesktop = (name: string) => JSON.stringify({
-  name,
-  desktop: {
-    window: { width: 1280, height: 800, minWidth: 640, minHeight: 480 },
-  },
-}, null, 2) + "\n"
-
-const readmeTemplate = (name: string) => `# ${name}
-
-A LeCodes app. The whole SDK is available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) —
-no imports needed. \`main.ts\` is the entry point.
-
-## Run it
-
-\`\`\`
-lecodes dev                  # live on your phone: scan the QR with the LeCodes app, hot reload
-lecodes compile -o app.js    # bundle to a single self-contained JS file
-\`\`\`
-
-## Test it (no device needed)
-
-\`\`\`
-lecodes render --png shot.png    # headless screenshot of the running app
-lecodes test                     # run tests/*.flow.json — the starter ships with a passing one
-\`\`\`
-
-Scenario format + conventions: see [CLAUDE.md](./CLAUDE.md) (written for AI assistants, useful
-for humans too).
-
-## Put it on the platform
-
-This project is local-only. To give it a home on le.codes (web editor, sharing, OTA updates):
-
-\`\`\`
-lecodes login                    # once per machine
-lecodes link                     # create a project from this folder and connect it
-lecodes push -m "initial"        # upload it as the first checkpoint (--publish to go live)
-\`\`\`
-
-Already made the project in the web editor? \`lecodes link --project <uuid>\` adopts it — it
-shows what your next push would change there before connecting anything.
-
-## Go native
-
-\`\`\`
-lecodes app init ios         # generate a native Xcode shell in ios/
-lecodes app sync             # embed the compiled bundle + plugins into it
-lecodes app open             # open it in Xcode, build & run
-\`\`\`
-
-## Layout
-
-- \`main.ts\` — the app's entry point. Add more .ts files freely and import them from
-  \`main.ts\`; a file named \`main.ts\` is always the entry.
-- \`tests/\` — headless flow tests (\`lecodes test\`); failing steps dump the frame to
-  \`tests/.artifacts/\`
-- \`CLAUDE.md\` — guidance for AI assistants (the headless feedback loop + testability conventions)
-- \`assets/\` — images/fonts the app references (created on demand)
-- \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit).
-  They come from the SDK bundled in the CLI; \`lecodes update\` refreshes them from the platform.
-- \`.lecodes/\` is gitignored — per-checkout state (those types + \`manifest.json\`, this machine's
-  sync cursor once linked). After a fresh git clone: \`lecodes update\`, then
-  \`lecodes link --project <uuid>\` to re-attach.
-- \`.lecodesignore\` — files a future \`lecodes push\` would skip
-
-Full command list: \`lecodes --help\`.
-`
-
-export default defineCommand({
-  name: "init",
-  summary: "Scaffold a new LOCAL project (no login, no server)",
-  usage: "[dir]",
-  description: "Writes a starter main.ts, a CLAUDE.md + a passing flow test (the headless render / test loop), the IDE types + tsconfig, and a .lecodesignore. Run it with `lecodes dev` or `lecodes compile`. Idempotent: existing files are kept.",
-  flags: { desktop: bool("also write an app.json declaring the desktop target (window size; `dev --desktop`, `desktop run` and headless render / test pick it up)") },
-  examples: ["lecodes init myapp", "lecodes init --desktop"],
-  run: ({ args, flags }) => init(args[0], flags.desktop),
-})
-
-const init = (dir: string | undefined, forDesktop: boolean): void => {
-  const dirArg = (dir ?? ".").replace(/[/\\]+$/, "") || "."
-  const root = resolve(dirArg)
-  const name = basename(root)
-
-  mkdirSync(root, { recursive: true })
-
-  let created = 0
-  const write = (rel: string, content: string) => {
-    const abs = join(root, rel)
-    if (existsSync(abs)) { note(`kept      ${rel}`); return }
-    mkdirSync(dirname(abs), { recursive: true })
-    writeFileSync(abs, content)
-    log(`${c.green("created")}   ${rel}`)
-    created++
-  }
-
-  // Starter entry — a root file named main.ts is always the detected entrypoint.
-  write("main.ts", STARTER)
-  write("README.md", readmeTemplate(name))
-  // --desktop: an app.json declaring the desktop target (window config in logical units).
-  if (forDesktop) write("app.json", appJsonDesktop(name))
-  // AI-assistant guidance + a passing flow test: the headless loop is discoverable from day one.
-  write("CLAUDE.md", appClaudeMd(name))
-  write(".claude/settings.json", CLAUDE_SETTINGS)
-  write("tests/counter.flow.json", STARTER_FLOW)
-  // Keep local render/preview outputs (screenshot.png, shots/) out of any future push.
-  write(".lecodesignore", DEFAULT_IGNORE_FILE)
-  // .lecodes/ is per-checkout state (generated types + the push cursor) — keep it out of git.
-  const gi = ensureGitignore(root)
-  if (gi === "created") { log(`${c.green("created")}   .gitignore`); created++ }
-  else if (gi === "updated") log(`${c.green("updated")}   .gitignore  ${c.dim("(+ .lecodes/)")}`)
-  else note("kept      .gitignore")
-
-  // IDE types: the SDK's import-free global surface + a tsconfig, so VS Code resolves UIScreen,
-  // Scene2D, setLoop, … with no server. Regenerated every run to pick up CLI upgrades.
-  const wroteTypes = materializeTypesLocal(root)
-  writeTsconfig(root)
-  log(`${c.green("written")}   tsconfig.json${wroteTypes ? ` + ${LECODES_DIR}/types/` : ""}  (IDE types)`)
-  if (!wroteTypes) {
-    warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.")
-  }
-
-  log("")
-  success(created
-    ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.`
-    : `Project ${c.bold(name)} already initialized.`)
-  const cd = dirArg === "." ? "" : `cd ${dirArg} && `
-  if (forDesktop) {
-    log(`  ${c.bold(cd + "lecodes dev --desktop")}      run it in a desktop window with hot reload`)
-    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (desktop-sized)`)
-    log(`  ${c.bold(cd + "lecodes desktop run")}        open the compiled app in the desktop host`)
-  } else {
-    log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`)
-    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`)
-    log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`)
-  }
-}
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { LECODES_DIR } from "../../project/manifest"
+import { materializeTypesLocal, writeTsconfig } from "../../project/types"
+import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../../project/ignore"
+import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./templates"
+import { bool, c, defineCommand, log, note, success, warnErr } from "../../cli"
+
+/*
+ * `lecodes init [dir]` — scaffold a brand-new LOCAL project: no account, no login, no server.
+ *
+ * Writes a starter entry, a CLAUDE.md (the headless render/test workflow for AI assistants) with
+ * a passing starter flow test, the SDK's import-free type surface + a tsconfig (so VS Code gives
+ * full IntelliSense offline), and a `.lecodesignore`. The result runs immediately with `lecodes dev`
+ * (hot reload on a device) and compiles with `lecodes compile -o app.js` (a self-contained bundle
+ * for LeCodes Desktop). It's the offline counterpart to `lecodes create`, which makes a project on
+ * the server; a local project needs no manifest — `dev`/`compile` compile straight from the tree.
+ *
+ * Idempotent: existing files are kept (never clobbered), so it's safe to re-run or run in a folder
+ * that already has content. Only the generated tsconfig + `.lecodes/types/` are rewritten each run.
+ */
+
+const STARTER = `// Welcome to LeCodes — the whole SDK is available as globals, no imports needed.
+// Run it live on a device with \`lecodes dev\`, or bundle it with \`lecodes compile -o app.js\`.
+
+let count = 0
+
+const counter = UIText("Taps: 0").style({ color: "#9fb0d0", fontSize: 22, marginTop: 18 })
+
+const button = UIButton(UIText("Tap me").style({ color: "#ffffff", fontSize: 22 }))
+  .style({
+    backgroundColor: "#4f7cff",
+    borderRadius: 14,
+    paddingVertical: 16,
+    paddingHorizontal: 40,
+    marginTop: 24,
+    alignItems: "center",
+    justifyContent: "center",
+    $hovered: { backgroundColor: "#6b91ff" }, // the mouse over it (desktop); $pressed is the press
+  })
+  .named("tap") // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
+  .onClick(() => {
+    count++
+    counter.text = "Taps: " + count
+  })
+
+const screen = UIScreen(
+  UIColumn(UIText("Hello, LeCodes").style({ color: "#ffffff", fontSize: 32 }), button, counter)
+    .style({ backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" }),
+)
+  .style({ backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 })
+  .named("home") // the screen root's name is what tests' \`expect: { screen: … }\` reads
+
+screen.open()
+`
+
+/** `--desktop`: declare the desktop target up front. Window sizes are logical units (the host
+ *  scales for HiDPI); `dev --desktop` / `desktop run` / `render --desktop` all read this, and a
+ *  desktop-only app.json makes headless render/test default to the window size too. */
+const appJsonDesktop = (name: string) => JSON.stringify({
+  name,
+  desktop: {
+    window: { width: 1280, height: 800, minWidth: 640, minHeight: 480 },
+  },
+}, null, 2) + "\n"
+
+const readmeTemplate = (name: string) => `# ${name}
+
+A LeCodes app. The whole SDK is available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) —
+no imports needed. \`main.ts\` is the entry point.
+
+## Run it
+
+\`\`\`
+lecodes dev                  # live on your phone: scan the QR with the LeCodes app, hot reload
+lecodes compile -o app.js    # bundle to a single self-contained JS file
+\`\`\`
+
+## Test it (no device needed)
+
+\`\`\`
+lecodes render --png shot.png    # headless screenshot of the running app
+lecodes test                     # run tests/*.flow.json — the starter ships with a passing one
+\`\`\`
+
+Scenario format + conventions: see [CLAUDE.md](./CLAUDE.md) (written for AI assistants, useful
+for humans too).
+
+## Put it on the platform
+
+This project is local-only. To give it a home on le.codes (web editor, sharing, OTA updates):
+
+\`\`\`
+lecodes login                    # once per machine
+lecodes link                     # create a project from this folder and connect it
+lecodes push -m "initial"        # upload it as the first checkpoint (--publish to go live)
+\`\`\`
+
+Already made the project in the web editor? \`lecodes link --project <uuid>\` adopts it — it
+shows what your next push would change there before connecting anything.
+
+## Go native
+
+\`\`\`
+lecodes app init ios         # generate a native Xcode shell in ios/
+lecodes app sync             # embed the compiled bundle + plugins into it
+lecodes app open             # open it in Xcode, build & run
+\`\`\`
+
+## Layout
+
+- \`main.ts\` — the app's entry point. Add more .ts files freely and import them from
+  \`main.ts\`; a file named \`main.ts\` is always the entry.
+- \`tests/\` — headless flow tests (\`lecodes test\`); failing steps dump the frame to
+  \`tests/.artifacts/\`
+- \`CLAUDE.md\` — guidance for AI assistants (the headless feedback loop + testability conventions)
+- \`assets/\` — images/fonts the app references (created on demand)
+- \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit).
+  They come from the SDK bundled in the CLI; \`lecodes update\` refreshes them from the platform.
+- \`.lecodes/\` is gitignored — per-checkout state (those types + \`manifest.json\`, this machine's
+  sync cursor once linked). After a fresh git clone: \`lecodes update\`, then
+  \`lecodes link --project <uuid>\` to re-attach.
+- \`.lecodesignore\` — files a future \`lecodes push\` would skip
+
+Full command list: \`lecodes --help\`.
+`
+
+export default defineCommand({
+  name: "init",
+  summary: "Scaffold a new LOCAL project (no login, no server)",
+  usage: "[dir]",
+  description: "Writes a starter main.ts, a CLAUDE.md + a passing flow test (the headless render / test loop), the IDE types + tsconfig, and a .lecodesignore. Run it with `lecodes dev` or `lecodes compile`. Idempotent: existing files are kept.",
+  flags: { desktop: bool("also write an app.json declaring the desktop target (window size; `dev --desktop`, `desktop run` and headless render / test pick it up)") },
+  examples: ["lecodes init myapp", "lecodes init --desktop"],
+  run: ({ args, flags }) => init(args[0], flags.desktop),
+})
+
+const init = (dir: string | undefined, forDesktop: boolean): void => {
+  const dirArg = (dir ?? ".").replace(/[/\\]+$/, "") || "."
+  const root = resolve(dirArg)
+  const name = basename(root)
+
+  mkdirSync(root, { recursive: true })
+
+  let created = 0
+  const write = (rel: string, content: string) => {
+    const abs = join(root, rel)
+    if (existsSync(abs)) { note(`kept      ${rel}`); return }
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+    log(`${c.green("created")}   ${rel}`)
+    created++
+  }
+
+  // Starter entry — a root file named main.ts is always the detected entrypoint.
+  write("main.ts", STARTER)
+  write("README.md", readmeTemplate(name))
+  // --desktop: an app.json declaring the desktop target (window config in logical units).
+  if (forDesktop) write("app.json", appJsonDesktop(name))
+  // AI-assistant guidance + a passing flow test: the headless loop is discoverable from day one.
+  write("CLAUDE.md", appClaudeMd(name))
+  write(".claude/settings.json", CLAUDE_SETTINGS)
+  write("tests/counter.flow.json", STARTER_FLOW)
+  // Keep local render/preview outputs (screenshot.png, shots/) out of any future push.
+  write(".lecodesignore", DEFAULT_IGNORE_FILE)
+  // .lecodes/ is per-checkout state (generated types + the push cursor) — keep it out of git.
+  const gi = ensureGitignore(root)
+  if (gi === "created") { log(`${c.green("created")}   .gitignore`); created++ }
+  else if (gi === "updated") log(`${c.green("updated")}   .gitignore  ${c.dim("(+ .lecodes/)")}`)
+  else note("kept      .gitignore")
+
+  // IDE types: the SDK's import-free global surface + a tsconfig, so VS Code resolves UIScreen,
+  // Scene2D, setLoop, … with no server. Regenerated every run to pick up CLI upgrades.
+  const wroteTypes = materializeTypesLocal(root)
+  writeTsconfig(root)
+  log(`${c.green("written")}   tsconfig.json${wroteTypes ? ` + ${LECODES_DIR}/types/` : ""}  (IDE types)`)
+  if (!wroteTypes) {
+    warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.")
+  }
+
+  log("")
+  success(created
+    ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.`
+    : `Project ${c.bold(name)} already initialized.`)
+  const cd = dirArg === "." ? "" : `cd ${dirArg} && `
+  if (forDesktop) {
+    log(`  ${c.bold(cd + "lecodes dev --desktop")}      run it in a desktop window with hot reload`)
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (desktop-sized)`)
+    log(`  ${c.bold(cd + "lecodes desktop run")}        open the compiled app in the desktop host`)
+  } else {
+    log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`)
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`)
+    log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`)
+  }
+}