zelune 0.0.0-stage → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to the **Zelune — React Native Visual Canvas & MCP** project are documented in this file.
+
+## [1.4.0] - 2026-10-21
+
+### Added
+- **One-Command Project Installer (`zelune init` in `bin/cli.mjs`)**: Running `zelune init` inside any React Native or Expo repository automatically detects its screens directory (`src/screens/`, `screens/`, `app/`, `src/app/`), adds `"canvas": "zelune"` to `package.json`, configures the `zelune` MCP server in `mcp_config.json`, installs the AI agent skill to `.agents/skills/zelune/SKILL.md`, creates starter `DESIGN.md` and `PRODUCT.md` governance docs if missing, and adds `.canvas-layout.json` to `.gitignore`.
+- **Smart Zero-Flag CLI Launch (`bin/cli.mjs`)**: Running `zelune` with no flags automatically probes both IPv4 (`127.0.0.1`) and IPv6 (`::1`) interfaces starting at port `5173` to select a conflict-free port and opens the browser automatically via `--open` (disable with `--no-open`).
+- **Public npm Registry Metadata (`package.json`)**: Added `license`, `repository`, `homepage`, and `bugs` fields for publishing `zelune` to the public npm registry.
+
+## [1.3.0] - 2026-10-21
+
+### Added
+- **Universal Vite Virtual Screen Loader (`plugins/viteVirtualScreensPlugin.ts`, `src/screens/index.ts`, `vite.config.ts`)**: Replaced static screen imports with `virtual:zelune-screens` so running `zelune --project /path/to/app` dynamically discovers and mounts `.tsx` and `.jsx` screens from any React Native or Expo project (`src/screens/`, `screens/`, `app/`, `src/app/`, including nested route folders like `app/(tabs)/index.tsx`).
+- **Expo Router, React Navigation & Safe Area Browser Shims (`src/runtime/MockNavigationContext.tsx`, `vite.config.ts`)**: Added built-in web shims for `@react-navigation/native`, `expo-router` (`useRouter`, `useLocalSearchParams`, `Link`, `Stack`, `Tabs`), `react-native-safe-area-context` (`SafeAreaView`, `useSafeAreaInsets`), `expo-status-bar`, `lucide-react-native`, and automatic `tsconfig.json` `paths` alias (`@/`) resolution for external projects.
+
+## [1.2.1] - 2026-10-21
+
+### Added
+- **Collapsible Studio Side Panels (`src/canvas/CanvasApp.tsx`, `src/canvas/InspectorPanel.tsx`, `src/styles.css`)**: Added collapsible left (Screens Navigator) and right (AST Visual Inspector) sidebars with top-bar toggles, inline panel close buttons, floating canvas restore pills when collapsed, `[` and `]` keyboard shortcuts, auto-expand on element selection, and `220ms` `--ease-out-expo` width choreography.
+- **Minimal Studio Header Identity & Icon-First Hover-Reveal Toolbar (`src/canvas/CanvasApp.tsx`, `src/styles.css`, `src/server/apiMiddleware.ts`, `vite.config.ts`)**: Simplified the top-left studio brand header to display **Zelune** and the connected project name (`projectName`), set studio visual density permanently to `5/10` (`spacious`), and converted toolbar buttons (`Inspect & Edit`, `Interact & Navigate`, `Flow Graph`, `Fit`, `Grid`) into compact icon buttons that smoothly expand to reveal their text labels on hover/focus using `interpolate-size: allow-keywords` and `calc-size(max-content, size)`.
+
+### Fixed
+- **Browser Whole-Page Trackpad Pinch-Zoom Leak (`src/canvas/CanvasApp.tsx`, `src/styles.css`)**: Replaced React's passive `onWheel` handler with non-passive (`{ passive: false }`) native `wheel` and WebKit `gesturestart`/`gesturechange`/`gestureend` listeners plus `touch-action: none` and `overscroll-behavior: none`, preventing native browser page zoom anywhere in the studio and routing two-finger trackpad pinches into cursor-centered focal canvas zooming.
+
+## [1.2.0] - 2026-10-20
+
+### Added
+- **Design Craft & Product Truth System (`PRODUCT.md`, `DESIGN.md`)**: Established `pbakaus/impeccable` product truth and YAML-governed design tokens, `leonxlnx/taste-skill` dual-surface parametric dials (`Design Variance`, `Motion Intensity`, `Visual Density`), and `emilkowalski/skills` motion and touch ergonomics contracts.
+- **Interactive Taste Density Switcher (`src/canvas/CanvasApp.tsx`, `src/styles.css`)**: Added a live `Density 8/10 (Cockpit)` vs. `Density 5/10 (Comfort)` toggle using CSS `data-density` + `@container style(--density: ...)` reactive tokens.
+- **Physics-Inspired Camera Transitions & Micro-Interactions (`src/canvas/CanvasApp.tsx`, `src/canvas/ScreenArtboard.tsx`, `src/styles.css`)**: Added `--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1)` camera interpolation for screen focus/fit actions (with a `0ms` direct-manipulation override during pointer drag/wheel zoom), `scale: 0.97` tactile press feedback, `<dialog>` entry choreography, and `tabular-nums` alignment across all coordinate and zoom readouts.
+
+### Changed
+- **Anti-Slop Visual Overhaul (`index.html`, `src/canvas/*`, `src/screens/*`)**: Replaced generic `Inter` typography with `Plus Jakarta Sans` + `JetBrains Mono`, removed cliché purple-to-cyan/violet button gradients in favor of tinted obsidian surfaces (`#08090C` / `#0D0F14` / `#13161E`) and `1px` hairlines, and replaced emoji card placeholders (`🎧`, `⌨️`) across the React Native reference screens with industrial hardware monograms (`CH-01`, `KS-75`) and `activeOpacity={0.78}` mobile touch ergonomics.
+
+## [1.1.1] - 2026-10-20
+
+### Changed
+- **Zelune MCP & Package Branding (`mcp/server.ts`, `mcp_config.json`, `plugin.json`, `package.json`, `src/canvas/`)**: Renamed the MCP server, CLI binary (`npx zelune`), plugin manifest, and canvas studio header to **Zelune** (`zelune`).
+
+## [1.1.0] - 2026-10-20
+
+### Added
+- **Universal CLI Entrypoint (`bin/cli.mjs`)**: Added CLI binary supporting `--project /path/to/app`, `--port`, and `--mcp` flags, plus automatic screen discovery across `src/screens/`, `screens/`, and Expo Router `app/` directories.
+- **Google Antigravity Plugin Bundle (`plugin.json`, `mcp_config.json`, `skills/rn-canvas/SKILL.md`, `rules/AGENTS.md`, `assets/logo.svg`)**: Packaged the workspace as a complete installable Antigravity Plugin and public npm package.
+
+## [1.0.0] - 2026-10-20
+
+### Added
+- **Browser Infinite Canvas (`src/canvas/CanvasApp.tsx`, `src/canvas/ScreenArtboard.tsx`)**: Built a 60fps Figma-style pan-and-zoom visual canvas rendering all React Native screens side-by-side on clean rectangular `393 × 852` artboards without bulky hardware device bezels.
+- **Compile-Time JSX Source & AST Path Injector (`plugins/viteRnSourceInject.ts`)**: Created a custom Babel/Vite transform that injects deterministic `dataSet` and `data-agy-*` source coordinates into React Native elements so `react-native-web` DOM nodes map directly back to `.tsx` AST nodes.
+- **Two-Tier Bi-Directional AST Engine (`src/server/astEngine.ts`, `src/server/apiMiddleware.ts`)**:
+  - **Tier 1 (Surgical AST Patching)**: Live inspection and mutation of `StyleSheet.create` rules, inline styles, and static `<Text>` copy with per-file write mutex locking and a 50-step Undo/Redo history stack (`Cmd+Z` / `Cmd+Shift+Z`).
+  - **Tier 2 (Google Antigravity Agent Bridge & MCP Server)**: Added an in-canvas "Ask Antigravity to Refactor" modal (`<dialog closedby="any">`) and a standalone MCP server (`mcp/server.ts`) exposing `list_canvas_screens`, `inspect_screen_element`, and `patch_screen_element`.
+- **Automatic Navigation Flow Graph (`src/canvas/FlowArrowsLayer.tsx`)**: Extracts `navigation.navigate(...)` and `router.push(...)` calls from screen ASTs and renders interactive cubic-bezier SVG flow connectors across the infinite canvas.
+- **Multi-Screen React Native Starter Suite (`src/screens/`)**: Added `LoginScreen.tsx`, `HomeScreen.tsx`, `ProductDetailScreen.tsx`, `CheckoutScreen.tsx`, and `ProfileScreen.tsx` wrapped in `MockNavigationProvider` and `ScreenErrorBoundary`.

package/DESIGN.md

@@ -0,0 +1,90 @@
+---
+system: zelune-design-system
+version: 1.2.0
+frameworks:
+  - pbakaus/impeccable
+  - emilkowalski/skills
+  - leonxlnx/taste-skill
+taste_dials:
+  studio_chrome:
+    design_variance: 2
+    motion_intensity: 6
+    visual_density: 5
+  mobile_reference_screens:
+    design_variance: 7
+    motion_intensity: 7
+    visual_density: 4
+tokens:
+  fonts:
+    sans: "'Plus Jakarta Sans', -apple-system, BlinkMacSystemFont, sans-serif"
+    mono: "'JetBrains Mono', ui-monospace, SFMono-Regular, monospace"
+  colors:
+    studio_canvas_bg: "#08090C"
+    studio_surface_1: "#0D0F14"
+    studio_surface_2: "#13161E"
+    studio_surface_3: "#191D28"
+    studio_border_hairline: "rgba(255, 255, 255, 0.07)"
+    studio_border_subtle: "#1E2330"
+    studio_border_focus: "#38BDF8"
+    studio_text_primary: "#F1F5F9"
+    studio_text_secondary: "#94A3B8"
+    studio_text_muted: "#64748B"
+    studio_accent_primary: "#38BDF8"
+    studio_accent_Select: "#6366F1"
+    studio_accent_interact: "#10B981"
+    studio_accent_warning: "#F59E0B"
+    studio_accent_danger: "#F43F5E"
+  motion:
+    ease_out: "cubic-bezier(0.23, 1, 0.32, 1)"
+    ease_out_expo: "cubic-bezier(0.16, 1, 0.3, 1)"
+    ease_in_out: "cubic-bezier(0.65, 0, 0.35, 1)"
+    duration_press: "120ms"
+    duration_micro: "160ms"
+    duration_panel: "220ms"
+    duration_camera: "380ms"
+    press_scale: 0.97
+---
+
+# DESIGN.md — Zelune Visual & Motion System
+
+This specification governs visual craftsmanship, parametric taste dials, physics-based motion curves, and anti-slop guardrails across **Zelune**.
+
+---
+
+## 1. Parametric Taste Dials (`leonxlnx/taste-skill`)
+
+Before modifying any component, configure the three gating dials according to the target surface:
+
+| Surface | Design Variance (1–10) | Motion Intensity (1–10) | Visual Density (1–10) | Aesthetic Mandate |
+| :--- | :---: | :---: | :---: | :--- |
+| **Zelune Studio Chrome** (`src/canvas/`) | **2 / 10** | **6 / 10** | **8 / 10** | **Pilot Cockpit Precision**: Strict orthogonal alignment, `1px` hairline borders (`rgba(255,255,255,0.07)`), `tabular-nums` coordinate readouts, and switchable `compact` / `spacious` inspector density. |
+| **Chronos Mobile Suite** (`src/screens/`) | **7 / 10** | **7 / 10** | **4 / 10** | **Industrial Editorial**: Asymmetric spec grids, technical model numbers (`CH-01 // BERYLLIUM`), high-contrast typographic hierarchy, and generous negative space. |
+
+---
+
+## 2. Motion & Touch Ergonomics (`emilkowalski/skills`)
+
+### 2.1 Easing & Timing Tokens
+- **Never use `ease-in` on entering or interactive UI elements.** Built-in CSS `ease` and `linear` are prohibited for UI feedback.
+- **`--ease-out: cubic-bezier(0.23, 1, 0.32, 1)`**: Default curve for button hovers, inspector pills, and bounding-box overlays (`140ms–180ms`).
+- **`--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1)`**: High-velocity decelerating curve for programmatic canvas camera focus (`focusOnScreen`, `handleFitAllScreens`, `380ms`) and `<dialog>` modal entry (`200ms`).
+- **Direct Manipulation Override (`0ms`)**: When the user is actively dragging the canvas (`isPanning`) or scrolling the wheel (`onWheel`), `transition` on the world transform container **must be `none`** so the canvas tracks the cursor with zero latency.
+
+### 2.2 Tactile Press Feedback & Stacking Context Stability
+- All interactive studio buttons, swatches, and pills apply an identity transform (`scale: 1; translate: 0 0;`) at rest to prevent stacking-context shifts, and compress to `scale: 0.97` on `:active` over `120ms var(--ease-out)`.
+- Respect `prefers-reduced-motion: reduce` by collapsing camera and micro-interaction durations.
+
+### 2.3 Mobile Touch Ergonomics (`src/screens/`)
+- Every `<TouchableOpacity>` on the `393 × 852` artboards must provide a minimum `40px–48px` vertical touch target (`paddingVertical: 10–16`) and explicit `activeOpacity={0.78}` for tactile mobile responsiveness.
+
+---
+
+## 3. Anti-Slop Rules (`pbakaus/impeccable`)
+
+The following AI-generated design clichés are **strictly banned** in this repository:
+
+1. **No Default `Inter` Monoculture**: Use `'Plus Jakarta Sans'` for UI/display copy paired with `'JetBrains Mono'` (`font-variant-numeric: tabular-nums`) for AST paths, line numbers, dimensions, zoom percentages, and prices.
+2. **No Cliché Purple-to-Cyan / Indigo-to-Violet Button Gradients**: Do not slap `linear-gradient(135deg, #4F46E5, #7C3AED)` or `#06B6D4` gradients onto studio logos or primary CTAs. Use solid, high-craft tinted surfaces (`#13161E`), crisp 1px hairlines, and deliberate single-hue signal accents (`#38BDF8` sky cyan for inspection, `#6366F1` precision indigo for AST selection, `#10B981` emerald for live navigation flows).
+3. **No Emoji-in-a-Rounded-Square Placeholders**: Never place raw emojis (`🎧`, `⌨️`) inside rounded colored squares as substitute product photography or feature icons. Use technical typographic monograms, model codes (`CH-01`, `KS-75`), or vector geometry.
+4. **No Untinted Pure Grays or Muddy Borders**: All dark neutrals must carry a subtle cool-obsidian tint (`#08090C` canvas, `#0D0F14` chrome, `#13161E` elevated controls) separated by `1px solid rgba(255, 255, 255, 0.07)` hairlines and soft diffusion shadows (`0 24px 48px -12px rgba(0, 0, 0, 0.72)`).
+5. **No Numeric Layout Jitter**: Every counter, zoom readout (`68%`), coordinate (`L142:8`), artboard dimension (`393 × 852`), and price (`$349.00`) must enforce `tabular-nums`.

package/PRODUCT.md

@@ -0,0 +1,31 @@
+# PRODUCT.md — Zelune (`zelune`)
+
+> Durable product truth anchored per the [`pbakaus/impeccable`](https://github.com/pbakaus/impeccable) context specification. All UI, motion, and agent-driven AST modifications must align with this document.
+
+## 1. Product Purpose
+**Zelune** is a **Figma-style multi-screen React Native visual canvas** and **bi-directional Babel AST synchronization MCP server** built for **Google Antigravity**. It eliminates the blind spot between mobile codebases (`.tsx`) and visual spatial architecture by rendering every screen side-by-side as pure `393 × 852` artboards with live navigation flow graphs and surgical AST write-back.
+
+## 2. Target Audience
+- **Design Engineers & Mobile Product Builders** working in React Native or Expo who demand Linear/Figma-grade precision tooling.
+- **AI Coding Agents (Google Antigravity)** operating via the `zelune` MCP server (`list_canvas_screens`, `inspect_screen_element`, `patch_screen_element`) that need deterministic spatial and style context.
+
+## 3. Operating Context & Dual-Surface Architecture
+Zelune contains two distinct visual surfaces that must never be conflated:
+
+1. **Surface A — Zelune Studio Chrome (`src/canvas/`)**
+   - **Context**: Desktop browser IDE/Canvas companion (`1280px–2560px+` viewports), used alongside a code editor for hours at a time.
+   - **Priority**: High information density, zero visual fatigue, instant spatial orientation, 1:1 pointer tracking during drag/zoom, and unambiguous AST source coordinates (`file:line:col`).
+2. **Surface B — Chronos Acoustics Reference Mobile Suite (`src/screens/`)**
+   - **Context**: `393 × 852` iOS/Android mobile artboards demonstrating multi-screen React Native inspection, live `StyleSheet.create` patching, and SVG navigation flow extraction.
+   - **Priority**: Industrial-grade hardware commerce aesthetic (inspired by Teenage Engineering / Bang & Olufsen), 44pt+ mobile touch ergonomics, and editorial typographic hierarchy.
+
+## 4. Core Constraints & Technical Invariants
+- **No Hardware Bezels**: Screens render on clean rectangular `393 × 852` artboards with `1px` architectural frames—never inside skeuomorphic phone clay frames or fake notches.
+- **Compile-Time AST Determinism**: Every React Native element maps back to its `.tsx` source node via `data-agy-ast-path`. Screen components must maintain a clean `StyleSheet.create` block at the bottom of the file.
+- **Two-Tier Edit Safety**:
+  - **Tier 1**: Surgical AST mutations for static `<Text>` copy and `StyleSheet.create` / inline style properties with per-file mutex locking and a 50-step Undo/Redo stack.
+  - **Tier 2**: Native `<dialog closedby="any">` structural refactor bridge + stdio MCP server for complex stateful or multi-node changes.
+
+## 5. Voice & Craft Tone
+- **Studio Chrome**: Clinical, technical, understated, and exact. Labels use concise engineering terminology (`AST Node`, `L42:8`, `styles.heroBanner`, `393 × 852`) rather than marketing fluff.
+- **Reference Mobile App**: Tactile, acoustic-engineering precision, confident editorial restraint.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# Zelune (`zelune`)
 
-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.
+**Zelune** is a **Figma-style multi-screen visual canvas** and **bi-directional Babel AST sync MCP server** for React Native & Expo applications in **Google Antigravity**, Cursor, and Claude Code.
+
+View all of your mobile screens side-by-side on clean `393 × 852` rectangular artboards in the browser, inspect any `<View>`, `<Text>`, or `<TouchableOpacity>` element, and edit copy or `StyleSheet.create` styles with instant write-back to your `.tsx` source code.
+
+---
+
+## Global Installation & Effortless Project Setup
+
+### 1. Install Globally Once (or via `npm link` locally)
+```bash
+npm install -g github:woodfur/antigravity-rn-canvas
+# Or once published to npm:
+npm install -g zelune
+```
+
+### 2. Initialize & Launch in Any React Native / Expo Project
+Inside any React Native or Expo project folder:
+
+```bash
+cd /path/to/your/react-native-app
+
+# Optional one-time project setup (adds "npm run canvas", mcp_config.json, AI skill, DESIGN.md & PRODUCT.md):
+zelune init
+
+# Launch the visual canvas (auto-selects a free port and opens your browser automatically):
+zelune
+```
+
+You can also run it without installing globally:
+```bash
+npx github:woodfur/antigravity-rn-canvas
+```
+
+### Option B: Install the Zelune AI Agent Skill
+Install the Zelune skill (`skills/rn-canvas/SKILL.md`), design system (`DESIGN.md`, `PRODUCT.md`), and AST rules (`rules/AGENTS.md`) into your AI coding agent:
+
+```bash
+npx skills add woodfur/antigravity-rn-canvas
+```
+
+---
+
+## Google Antigravity Integration (Zelune MCP Server)
+
+### 1. MCP Server Setup
+Add the **Zelune** MCP server to your `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zelune": {
+      "command": "npx",
+      "args": ["-y", "github:woodfur/antigravity-rn-canvas", "--mcp"]
+    }
+  }
+}
+```
+
+### 2. Available Zelune MCP Tools
+- `list_canvas_screens` — Lists all discovered screens (`src/screens/`, `screens/`, or Expo Router `app/`), element counts, and outgoing navigation flows.
+- `inspect_screen_element` — Returns the resolved `StyleSheet.create` / inline styles, static text copy, and JSX snippet for any element by `file` and `astPath`.
+- `patch_screen_element` — Surgically patches text copy or style rules in `.tsx` source files while preserving comments and formatting.

package/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" fill="none">
+  <rect x="14" y="14" width="100" height="100" rx="24" fill="#11141D" stroke="#4F46E5" stroke-width="4"/>
+  <rect x="28" y="30" width="28" height="56" rx="4" fill="#1E1B4B" stroke="#6366F1" stroke-width="2.5"/>
+  <rect x="72" y="42" width="28" height="56" rx="4" fill="#064E3B" stroke="#10B981" stroke-width="2.5"/>
+  <path d="M56 58 C64 58, 64 70, 72 70" stroke="#38BDF8" stroke-width="3" stroke-linecap="round"/>
+  <circle cx="56" cy="58" r="3.5" fill="#38BDF8"/>
+  <circle cx="72" cy="70" r="3.5" fill="#10B981"/>
+</svg>

package/bin/cli.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const defaultPackageRoot = path.resolve(__dirname, '..');
+
+function isHostPortFree(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.on('error', (err) => {
+      if (err && (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')) {
+        resolve(true);
+        return;
+      }
+      resolve(false);
+    });
+    server.listen({ port, host, exclusive: true }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+export async function isPortFree(port) {
+  const [ipv4Free, ipv6Free] = await Promise.all([
+    isHostPortFree(port, '127.0.0.1'),
+    isHostPortFree(port, '::1'),
+  ]);
+  return ipv4Free && ipv6Free;
+}
+
+export async function findAvailablePort(startPort = 5173, maxAttempts = 25) {
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const candidate = startPort + offset;
+    if (await isPortFree(candidate)) {
+      return candidate;
+    }
+  }
+  return startPort;
+}
+
+function detectScreensDirectory(targetProject) {
+  const candidates = ['src/screens', 'screens', 'app', 'src/app'];
+  for (const rel of candidates) {
+    const full = path.join(targetProject, rel);
+    if (fs.existsSync(full) && fs.statSync(full).isDirectory()) {
+      return rel;
+    }
+  }
+  return null;
+}
+
+export function initProject(targetProject, packageRoot = defaultPackageRoot) {
+  const resolvedTarget = path.resolve(targetProject);
+  const screensDir = detectScreensDirectory(resolvedTarget);
+
+  // 1. Update package.json with "canvas": "zelune" script if present
+  const pkgJsonPath = path.join(resolvedTarget, 'package.json');
+  let updatedPackageJson = false;
+  if (fs.existsSync(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+      pkg.scripts = pkg.scripts || {};
+      if (pkg.name !== 'zelune' && !pkg.scripts.canvas) {
+        pkg.scripts.canvas = 'zelune';
+        fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+        updatedPackageJson = true;
+      }
+    } catch {
+      // Ignore malformed package.json
+    }
+  }
+
+  // 2. Create or merge mcp_config.json with the zelune MCP server entry
+  const mcpConfigPath = path.join(resolvedTarget, 'mcp_config.json');
+  let mcpConfig = { mcpServers: {} };
+  if (fs.existsSync(mcpConfigPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'));
+      if (parsed && typeof parsed === 'object') {
+        mcpConfig = parsed;
+        mcpConfig.mcpServers = mcpConfig.mcpServers || {};
+      }
+    } catch {
+      mcpConfig = { mcpServers: {} };
+    }
+  }
+  mcpConfig.mcpServers.zelune = {
+    command: 'npx',
+    args: ['-y', 'zelune', '--mcp', '--project', resolvedTarget],
+  };
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
+
+  // 3. Install AI Agent Skill into .agents/skills/zelune/SKILL.md
+  const sourceSkillPath = path.join(packageRoot, 'skills/rn-canvas/SKILL.md');
+  const destSkillDir = path.join(resolvedTarget, '.agents/skills/zelune');
+  const destSkillPath = path.join(destSkillDir, 'SKILL.md');
+  if (fs.existsSync(sourceSkillPath)) {
+    fs.mkdirSync(destSkillDir, { recursive: true });
+    fs.copyFileSync(sourceSkillPath, destSkillPath);
+  }
+
+  // 4. Copy starter DESIGN.md & PRODUCT.md if not already present
+  let createdDesignMd = false;
+  const sourceDesignPath = path.join(packageRoot, 'DESIGN.md');
+  const destDesignPath = path.join(resolvedTarget, 'DESIGN.md');
+  if (fs.existsSync(sourceDesignPath) && !fs.existsSync(destDesignPath)) {
+    fs.copyFileSync(sourceDesignPath, destDesignPath);
+    createdDesignMd = true;
+  }
+
+  let createdProductMd = false;
+  const sourceProductPath = path.join(packageRoot, 'PRODUCT.md');
+  const destProductPath = path.join(resolvedTarget, 'PRODUCT.md');
+  if (fs.existsSync(sourceProductPath) && !fs.existsSync(destProductPath)) {
+    fs.copyFileSync(sourceProductPath, destProductPath);
+    createdProductMd = true;
+  }
+
+  // 5. Ensure .canvas-layout.json is listed in .gitignore
+  const gitignorePath = path.join(resolvedTarget, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const currentIgnore = fs.readFileSync(gitignorePath, 'utf8');
+    if (!currentIgnore.split(/\r?\n/).includes('.canvas-layout.json')) {
+      const prefix = currentIgnore.endsWith('\n') || currentIgnore.length === 0 ? '' : '\n';
+      fs.writeFileSync(
+        gitignorePath,
+        `${currentIgnore}${prefix}.canvas-layout.json\n`,
+        'utf8'
+      );
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, '.canvas-layout.json\n', 'utf8');
+  }
+
+  return {
+    targetProject: resolvedTarget,
+    screensDir: screensDir ?? 'src/screens (or app/)',
+    updatedPackageJson,
+    mcpConfigPath,
+    skillPath: destSkillPath,
+    createdDesignMd,
+    createdProductMd,
+  };
+}
+
+async function runCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Zelune — React Native Visual Canvas & AST Sync MCP Server
+
+Usage:
+  zelune                       Launch visual canvas for current project (auto-selects free port & opens browser)
+  zelune init                  One-command setup for the current React Native / Expo project
+  zelune --project <dir>       Target a specific React Native / Expo project directory
+  zelune --port <number>       Use a specific port (default: auto-detects from 5173)
+  zelune --no-open             Do not automatically open the browser on launch
+  zelune --mcp                 Start the Zelune stdio MCP server for Google Antigravity / Cursor / Claude Code
+`);
+    process.exit(0);
+  }
+
+  const isMcpMode = args.includes('--mcp');
+  const isInitMode = args[0] === 'init' || args[0] === 'setup';
+
+  let targetProject = process.cwd();
+  const projectFlagIdx = args.indexOf('--project');
+  if (projectFlagIdx !== -1 && args[projectFlagIdx + 1]) {
+    targetProject = path.resolve(args[projectFlagIdx + 1]);
+  }
+
+  if (isInitMode) {
+    const result = initProject(targetProject, defaultPackageRoot);
+    console.log(`\n✨ Zelune initialized in ${result.targetProject}`);
+    console.log(`   • Screens directory: ${result.screensDir}`);
+    if (result.updatedPackageJson) {
+      console.log(`   • Added "canvas": "zelune" script to package.json`);
+    }
+    console.log(`   • Configured MCP server in mcp_config.json`);
+    console.log(`   • Installed AI skill in .agents/skills/zelune/SKILL.md`);
+    if (result.createdDesignMd || result.createdProductMd) {
+      console.log(`   • Created starter DESIGN.md & PRODUCT.md governance docs`);
+    }
+    console.log(`\n👉 Run "npm run canvas" (or "zelune") to open your screens in the visual canvas!\n`);
+    process.exit(0);
+  }
+
+  const env = {
+    ...process.env,
+    ANTIGRAVITY_TARGET_PROJECT: targetProject,
+  };
+
+  if (isMcpMode) {
+    const mcpServerPath = path.join(defaultPackageRoot, 'mcp/server.ts');
+    const child = spawn('npx', ['tsx', mcpServerPath], {
+      cwd: defaultPackageRoot,
+      env,
+      stdio: 'inherit',
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    return;
+  }
+
+  const portFlagIdx = args.indexOf('--port');
+  let port;
+  if (portFlagIdx !== -1 && args[portFlagIdx + 1]) {
+    port = String(args[portFlagIdx + 1]);
+  } else {
+    const resolvedPort = await findAvailablePort(5173);
+    port = String(resolvedPort);
+  }
+
+  const shouldOpenBrowser = !args.includes('--no-open');
+  const viteArgs = ['vite', '--host', '127.0.0.1', '--port', port];
+  if (shouldOpenBrowser) {
+    viteArgs.push('--open');
+  }
+
+  console.log(`\n🚀 Zelune — React Native Visual Canvas & MCP`);
+  console.log(`📂 Target Project: ${targetProject}`);
+  console.log(`🌐 Studio URL:     http://127.0.0.1:${port}\n`);
+
+  const child = spawn('npx', viteArgs, {
+    cwd: defaultPackageRoot,
+    env,
+    stdio: 'inherit',
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+const isDirectExecution =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+
+if (isDirectExecution) {
+  runCli();
+}

package/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Zelune — React Native Visual Canvas &amp; AST Studio</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body class="bg-[#08090C] text-[#F1F5F9] antialiased selection:bg-sky-500/25 overflow-hidden">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/mcp/server.ts

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  discoverScreens,
+  inspectElement,
+  patchElement,
+  type StyleValue,
+} from '../src/server/astEngine.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_ROOT = path.resolve(__dirname, '..');
+
+const server = new Server(
+  {
+    name: 'zelune',
+    version: '1.3.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'list_canvas_screens',
+        description:
+          'Lists all discovered React Native screens on the visual canvas along with their element counts and outgoing navigation flow edges.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'inspect_screen_element',
+        description:
+          'Inspects a specific JSX element inside a React Native screen by its relative file path and AST index path.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: {
+              type: 'string',
+              description: 'Relative path to the screen file (e.g. src/screens/HomeScreen.tsx)',
+            },
+            astPath: {
+              type: 'string',
+              description: 'Preorder AST index of the JSX element (e.g. "0", "4")',
+            },
+          },
+          required: ['file', 'astPath'],
+        },
+      },
+      {
+        name: 'patch_screen_element',
+        description:
+          'Surgically patches the text copy or StyleSheet properties of a React Native JSX element.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            file: {
+              type: 'string',
+              description: 'Relative path to the screen file (e.g. src/screens/HomeScreen.tsx)',
+            },
+            astPath: {
+              type: 'string',
+              description: 'Preorder AST index of the JSX element',
+            },
+            text: {
+              type: 'string',
+              description: 'Optional new static text content for <Text> elements',
+            },
+            styles: {
+              type: 'object',
+              description: 'Optional map of React Native style properties to update',
+            },
+          },
+          required: ['file', 'astPath'],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name === 'list_canvas_screens') {
+    const screens = await discoverScreens(WORKSPACE_ROOT);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(screens, null, 2) }],
+    };
+  }
+
+  if (name === 'inspect_screen_element') {
+    const file = String(args?.file ?? '');
+    const astPath = String(args?.astPath ?? '0');
+    const element = await inspectElement(WORKSPACE_ROOT, { file, astPath });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(element, null, 2) }],
+    };
+  }
+
+  if (name === 'patch_screen_element') {
+    const file = String(args?.file ?? '');
+    const astPath = String(args?.astPath ?? '0');
+    const text = typeof args?.text === 'string' ? args.text : undefined;
+    const styles = (args?.styles as Record<string, StyleValue> | undefined) ?? undefined;
+
+    const result = await patchElement(WORKSPACE_ROOT, {
+      file,
+      astPath,
+      text,
+      styles,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+
+  throw new Error(`Unknown MCP tool: ${name}`);
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('MCP Server Error:', err);
+  process.exit(1);
+});