zelune 0.0.0-stage → 1.4.0

package/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "zelune": {
+      "command": "npx",
+      "args": ["-y", "zelune", "--mcp"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "zelune",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "description": "Zelune — Figma-style Multi-Screen React Native Visual Canvas & AST Sync MCP Server for Google Antigravity",
+  "homepage": "https://github.com/woodfur/antigravity-rn-canvas#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woodfur/antigravity-rn-canvas.git"
+  },
+  "bugs": {
+    "url": "https://github.com/woodfur/antigravity-rn-canvas/issues"
+  },
+  "keywords": [
+    "zelune",
+    "google-antigravity",
+    "react-native",
+    "expo",
+    "visual-canvas",
+    "ast",
+    "mcp",
+    "figma"
+  ],
+  "bin": {
+    "zelune": "bin/cli.mjs",
+    "antigravity-rn-canvas": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "plugins/",
+    "mcp/",
+    "skills/",
+    "rules/",
+    "assets/",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json",
+    "plugin.json",
+    "mcp_config.json",
+    "PRODUCT.md",
+    "DESIGN.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5173",
+    "canvas": "node ./bin/cli.mjs",
+    "build": "vite build",
+    "preview": "vite preview --host 127.0.0.1 --port 4173",
+    "test": "vitest run",
+    "mcp": "node ./bin/cli.mjs --mcp"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.25.0",
+    "@babel/parser": "^7.25.0",
+    "@babel/traverse": "^7.25.0",
+    "@babel/types": "^7.25.0",
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@vitejs/plugin-react": "^4.3.2",
+    "lucide-react": "^0.454.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-native-web": "^0.19.12",
+    "tsx": "^4.19.1",
+    "vite": "^5.4.8"
+  },
+  "devDependencies": {
+    "@types/babel__generator": "^7.6.8",
+    "@types/babel__traverse": "^7.20.6",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.11",
+    "@types/react-dom": "^18.3.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  }
+}

package/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "zelune",
+  "displayName": "Zelune — React Native Visual Canvas",
+  "version": "1.3.0",
+  "description": "Zelune MCP & Figma-style multi-screen React Native visual canvas with live surgical AST patching and navigation flow visualization for Google Antigravity.",
+  "logo": "assets/logo.svg",
+  "suggestedPrompts": [
+    "Use Zelune to list all discovered React Native screens and navigation flows",
+    "Use Zelune to inspect the primary CTA button on HomeScreen and update its background color and copy",
+    "Audit all screens on the Zelune visual canvas for consistent typography and spacing"
+  ]
+}

package/plugins/viteRnSourceInject.ts

@@ -0,0 +1,117 @@
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+import _generate from '@babel/generator';
+import * as t from '@babel/types';
+import path from 'node:path';
+import type { Plugin } from 'vite';
+
+// Handle ESM/CJS default export interop for @babel/* packages
+const traverse = (_traverse as unknown as { default?: typeof _traverse }).default ?? _traverse;
+const generate = (_generate as unknown as { default?: typeof _generate }).default ?? _generate;
+
+const ALLOWED_SCREEN_PREFIXES = ['src/screens/', 'screens/', 'app/', 'src/app/'];
+
+export function getJsxTagName(nameNode: t.JSXOpeningElement['name']): string {
+  if (t.isJSXIdentifier(nameNode)) {
+    return nameNode.name;
+  }
+  if (t.isJSXMemberExpression(nameNode)) {
+    return `${getJsxTagName(nameNode.object)}.${nameNode.property.name}`;
+  }
+  if (t.isJSXNamespacedName(nameNode)) {
+    return `${nameNode.namespace.name}:${nameNode.name.name}`;
+  }
+  return 'Unknown';
+}
+
+export function viteRnSourceInject(workspaceRoot: string): Plugin {
+  const normalizedRoot = path.resolve(workspaceRoot);
+
+  return {
+    name: 'vite-rn-source-inject',
+    enforce: 'pre',
+    transform(code: string, id: string) {
+      const cleanId = id.split('?')[0];
+      if (!cleanId.endsWith('.tsx') && !cleanId.endsWith('.jsx')) {
+        return null;
+      }
+
+      const resolvedFile = path.resolve(cleanId);
+      const relPath = path.relative(normalizedRoot, resolvedFile).replace(/\\/g, '/');
+
+      // Instrument screen files across src/screens/, screens/, app/, and src/app/
+      const isScreenFile = ALLOWED_SCREEN_PREFIXES.some((prefix) => relPath.startsWith(prefix));
+      if (!isScreenFile) {
+        return null;
+      }
+
+      try {
+        const ast = parse(code, {
+          sourceType: 'module',
+          plugins: ['typescript', 'jsx'],
+        });
+
+        let jsxIndex = 0;
+
+        traverse(ast, {
+          JSXOpeningElement(nodePath) {
+            const { node } = nodePath;
+            const tagName = getJsxTagName(node.name);
+
+            // Skip React.Fragment or Fragment since fragments do not accept DOM/dataSet props
+            if (tagName === 'Fragment' || tagName === 'React.Fragment' || tagName === '') {
+              return;
+            }
+
+            const currentIndex = String(jsxIndex++);
+            const line = String(node.loc?.start.line ?? 1);
+            const col = String(node.loc?.start.column ?? 0);
+
+            // Check if already injected
+            const hasAgyAttr = node.attributes.some(
+              (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: 'data-agy-ast-path' })
+            );
+            if (hasAgyAttr) {
+              return;
+            }
+
+            // Build dataSet={{ agyFile, agyLine, agyCol, agyAstPath, agyTag }} for react-native-web
+            const dataSetProps: t.ObjectProperty[] = [
+              t.objectProperty(t.identifier('agyFile'), t.stringLiteral(relPath)),
+              t.objectProperty(t.identifier('agyLine'), t.stringLiteral(line)),
+              t.objectProperty(t.identifier('agyCol'), t.stringLiteral(col)),
+              t.objectProperty(t.identifier('agyAstPath'), t.stringLiteral(currentIndex)),
+              t.objectProperty(t.identifier('agyTag'), t.stringLiteral(tagName)),
+            ];
+
+            node.attributes.push(
+              t.jsxAttribute(
+                t.jsxIdentifier('dataSet'),
+                t.jsxExpressionContainer(t.objectExpression(dataSetProps))
+              ),
+              t.jsxAttribute(t.jsxIdentifier('data-agy-file'), t.stringLiteral(relPath)),
+              t.jsxAttribute(t.jsxIdentifier('data-agy-line'), t.stringLiteral(line)),
+              t.jsxAttribute(t.jsxIdentifier('data-agy-col'), t.stringLiteral(col)),
+              t.jsxAttribute(t.jsxIdentifier('data-agy-ast-path'), t.stringLiteral(currentIndex)),
+              t.jsxAttribute(t.jsxIdentifier('data-agy-tag'), t.stringLiteral(tagName))
+            );
+          },
+        });
+
+        const output = generate(ast, {
+          retainLines: true,
+          sourceMaps: true,
+          sourceFileName: relPath,
+        });
+
+        return {
+          code: output.code,
+          map: output.map,
+        };
+      } catch {
+        // Return untransformed code so Vite's error overlay or ScreenErrorBoundary can report it cleanly
+        return null;
+      }
+    },
+  };
+}

package/plugins/viteVirtualScreensPlugin.ts

@@ -0,0 +1,85 @@
+import type { Plugin } from 'vite';
+import { discoverScreenFilesSync } from '../src/server/astEngine';
+
+const VIRTUAL_MODULE_ID = 'virtual:zelune-screens';
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
+
+const PREFERRED_ORDER = ['Login', 'Home', 'ProductDetail', 'Checkout', 'Profile'];
+
+/**
+ * Vite Virtual Module plugin that dynamically discovers and imports React Native / Expo
+ * screen components from any target project (`--project /path/to/app`).
+ */
+export function viteVirtualScreensPlugin(workspaceRoot: string): Plugin {
+  return {
+    name: 'vite-virtual-zelune-screens',
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_MODULE_ID;
+      }
+      return null;
+    },
+    load(id) {
+      if (id !== RESOLVED_VIRTUAL_MODULE_ID) {
+        return null;
+      }
+
+      const discovered = discoverScreenFilesSync(workspaceRoot);
+      const importLines: string[] = [
+        `import React from 'react';`,
+        `function resolveScreenComponent(mod) {`,
+        `  if (!mod) return null;`,
+        `  if (typeof mod.default === 'function' || (typeof mod.default === 'object' && mod.default !== null)) {`,
+        `    return mod.default;`,
+        `  }`,
+        `  for (const key of Object.keys(mod)) {`,
+        `    if (typeof mod[key] === 'function') return mod[key];`,
+        `  }`,
+        `  return null;`,
+        `}`,
+      ];
+
+      const mapEntries: string[] = [];
+      const orderIds: string[] = [];
+
+      const sorted = [...discovered].sort((a, b) => {
+        const idxA = PREFERRED_ORDER.indexOf(a.id);
+        const idxB = PREFERRED_ORDER.indexOf(b.id);
+        if (idxA !== -1 && idxB !== -1) return idxA - idxB;
+        if (idxA !== -1) return -1;
+        if (idxB !== -1) return 1;
+        return a.id.localeCompare(b.id);
+      });
+
+      sorted.forEach((scr, index) => {
+        const varName = `_screenMod_${index}`;
+        const normalizedFullPath = scr.fullPath.replace(/\\/g, '/');
+        importLines.push(`import * as ${varName} from ${JSON.stringify(normalizedFullPath)};`);
+        mapEntries.push(`  ${JSON.stringify(scr.id)}: resolveScreenComponent(${varName})`);
+        orderIds.push(scr.id);
+      });
+
+      return [
+        ...importLines,
+        `export const SCREEN_COMPONENTS = {`,
+        mapEntries.join(',\n'),
+        `};`,
+        `export const SCREEN_ORDER = ${JSON.stringify(orderIds)};`,
+      ].join('\n');
+    },
+    configureServer(server) {
+      server.watcher.on('add', (file) => {
+        if (file.endsWith('.tsx') || file.endsWith('.jsx')) {
+          const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+          if (mod) server.moduleGraph.invalidateModule(mod);
+        }
+      });
+      server.watcher.on('unlink', (file) => {
+        if (file.endsWith('.tsx') || file.endsWith('.jsx')) {
+          const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+          if (mod) server.moduleGraph.invalidateModule(mod);
+        }
+      });
+    },
+  };
+}

package/rules/AGENTS.md

@@ -0,0 +1,21 @@
+# Zelune React Native Visual Canvas & Craft Rules
+
+When modifying React Native/Expo screens or the Zelune Studio Canvas:
+
+1. **Design System & Product Truth (`pbakaus/impeccable`)**:
+   - Always consult `PRODUCT.md` and `DESIGN.md` before modifying colors, typography, or layout.
+   - **Anti-Slop Enforcement**: Never introduce default `Inter` font stacks, purple-to-cyan/violet button gradients (`linear-gradient(135deg, #4F46E5, #7C3AED)`), untinted pure grays, or raw emoji icons (`🎧`, `⌨️`) inside rounded squares.
+   - Apply `font-variant-numeric: tabular-nums` (`.tabular-nums`) to all coordinates, line numbers, dimensions (`393 × 852`), zoom percentages, and prices.
+
+2. **Motion & Touch Ergonomics (`emilkowalski/skills`)**:
+   - Use `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)` for interactive hover/press states and `--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1)` for programmatic camera focus/fit transitions.
+   - Maintain `0ms` transition override during direct pointer canvas panning and wheel zooming.
+   - Every React Native `<TouchableOpacity>` must include `activeOpacity={0.78}` and ergonomic vertical touch padding.
+
+3. **Parametric Taste Dials (`leonxlnx/taste-skill`)**:
+   - Keep Studio Chrome at `Design Variance: 2/10`, `Motion Intensity: 6/10`, `Visual Density: 8/10` (supporting reactive `data-density="compact" | "spacious"` tokens).
+   - Keep Mobile Reference Screens at `Design Variance: 7/10`, `Motion Intensity: 7/10`, `Visual Density: 4/10`.
+
+4. **AST Engine Invariants**:
+   - Preserve `StyleSheet.create` declarations at the bottom of screen `.tsx` files so Tier-1 AST inspection and surgical style patching remain deterministic.
+   - Use `useNavigation()` (`navigation.navigate('RouteName')`) or Expo Router (`router.push('/route')`) for screen transitions so the canvas automatically extracts SVG navigation flow arrows.

package/skills/rn-canvas/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: zelune
+description: Launch, inspect, and surgically patch React Native / Expo screens on the Zelune Figma-style multi-screen visual canvas. Enforces pbakaus/impeccable anti-slop rules, emilkowalski/skills motion physics, and leonxlnx/taste-skill parametric dials via PRODUCT.md and DESIGN.md.
+---
+
+# Zelune — React Native Visual Canvas & Craft Governance (`zelune`)
+
+Use this skill when working with React Native or Expo mobile applications in Google Antigravity to provide a live multi-screen Figma-style visual canvas synchronized with `.tsx` source files via the **Zelune** MCP server.
+
+## 1. Mandatory Pre-Flight Context (`pbakaus/impeccable`)
+Before generating or patching any UI component, read:
+- **`PRODUCT.md`** — Durable product truth, target audience, and dual-surface architecture.
+- **`DESIGN.md`** — Governed color tokens, typography hierarchy, motion curves, and anti-slop guardrails.
+
+## 2. Parametric Taste Dials (`leonxlnx/taste-skill`)
+Configure your structural and visual choices according to the surface:
+- **Studio Chrome (`src/canvas/`)**: `Design Variance: 2/10`, `Motion Intensity: 6/10`, `Visual Density: 8/10` (Cockpit precision, `1px` hairlines, `tabular-nums`, switchable `compact`/`spacious` density).
+- **Mobile Artboards (`src/screens/`)**: `Design Variance: 7/10`, `Motion Intensity: 7/10`, `Visual Density: 4/10` (Editorial hardware hierarchy, technical spec monograms, generous negative space).
+
+## 3. Motion & Touch Ergonomics (`emilkowalski/skills`)
+- **Easing Curves**: Never use `ease-in` for entering elements. Use `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)` (`120ms–160ms`) for micro-interactions and `--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1)` (`380ms`) for camera focus transitions.
+- **Tactile Feedback**: Apply `scale: 0.97` on `:active` (with base `scale: 1` to preserve stacking context) for web studio controls, and `activeOpacity={0.78}` with ≥44pt vertical targets on React Native `<TouchableOpacity>` elements.
+
+## 4. Available Zelune MCP Tools (`zelune`)
+1. **`list_canvas_screens`** — Lists all discovered React Native screens (`src/screens/`, `screens/`, or Expo Router `app/`), their JSX element counts, and outgoing navigation flow edges.
+2. **`inspect_screen_element`** — Given `{ file, astPath }`, returns the exact JSX element's tag name, line/column coordinates, static text copy, resolved `StyleSheet.create` or inline style properties, and JSX snippet.
+3. **`patch_screen_element`** — Surgically patches `{ file, astPath, text, styles }` directly in the `.tsx` source file while preserving comments, formatting, and dynamic expressions.
+
+## 5. Launching the Zelune Browser Canvas
+```bash
+npx zelune --project /path/to/react-native-app
+```
+Then open `http://127.0.0.1:5173`.