framer-code-link 0.7.0 → 0.10.0

package/dist/index.mjs

@@ -2,14 +2,15 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import fs from "fs/promises";
-import { WebSocketServer } from "ws";
 import path from "path";
+import { WebSocketServer } from "ws";
 import { createHash } from "crypto";
 import { setupTypeAcquisition } from "@typescript/ata";
 import ts from "typescript";
+import { fileURLToPath } from "node:url";
 import chokidar from "chokidar";
 
-//#region rolldown:runtime
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -1042,6 +1043,113 @@ function extractPackageFromUrl(url) {
 	return /\/(@?[^@/]+(?:\/[^@/]+)?)/.exec(url)?.[1] ?? null;
 }
 
+//#endregion
+//#region src/helpers/skills.ts
+/**
+* Agent Skills installer — copies the skill into the project directory
+* and symlinks it into agent-specific paths.
+*/
+/** Agent-specific skill directories that get symlinked to the canonical .skills/ location */
+const AGENT_SKILL_DIRS = [
+	".agents/skills",
+	".claude/skills",
+	".cursor/skills"
+];
+/**
+* Read the skill name from the SKILL.md frontmatter.
+*/
+async function readSkillName(sourceDir) {
+	const content = await fs.readFile(path.join(sourceDir, "SKILL.md"), "utf-8");
+	const match = /^name:\s*(.+)$/m.exec(content);
+	if (!match) throw new Error("Could not read skill name from SKILL.md frontmatter");
+	return match[1].trim();
+}
+/**
+* Recursively collect all file paths relative to a directory.
+*/
+async function collectFiles(dir, base = "") {
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const rel = base ? `${base}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) files.push(...await collectFiles(path.join(dir, entry.name), rel));
+		else files.push(rel);
+	}
+	return files;
+}
+/**
+* Install the agent skill into the project.
+* Writes the canonical skill to .skills/<name>/ and symlinks
+* into agent-specific directories.
+*/
+async function installSkills(projectDir) {
+	const sourceDir = await findSkillsSourceDir();
+	if (!sourceDir) {
+		debug("Could not locate skills source files, skipping skill installation");
+		return;
+	}
+	const skillName = await readSkillName(sourceDir);
+	const canonicalDir = path.join(projectDir, ".skills", skillName);
+	const skillMdPath = path.join(canonicalDir, "SKILL.md");
+	try {
+		await fs.access(skillMdPath);
+		debug("Agent skills already installed");
+		return;
+	} catch {}
+	const files = await collectFiles(sourceDir);
+	for (const file of files) {
+		const src = path.join(sourceDir, file);
+		const dest = path.join(canonicalDir, file);
+		try {
+			await fs.mkdir(path.dirname(dest), { recursive: true });
+			await fs.copyFile(src, dest);
+		} catch (err) {
+			debug(`Failed to copy skill file ${file}`, err);
+			return;
+		}
+	}
+	debug(`Installed agent skill to .skills/${skillName}/`);
+	for (const agentDir of AGENT_SKILL_DIRS) {
+		const linkDir = path.join(projectDir, agentDir);
+		const linkPath = path.join(linkDir, skillName);
+		const relativeTarget = path.relative(linkDir, canonicalDir);
+		try {
+			await fs.mkdir(linkDir, { recursive: true });
+			try {
+				const stat = await fs.lstat(linkPath);
+				if (stat.isSymbolicLink() || stat.isDirectory()) await fs.rm(linkPath, { recursive: true });
+			} catch {}
+			await fs.symlink(relativeTarget, linkPath, "dir");
+			debug(`Symlinked ${agentDir}/${skillName} -> ${relativeTarget}`);
+		} catch (err) {
+			debug(`Symlink failed for ${agentDir}, falling back to copy`, err);
+			try {
+				await fs.cp(canonicalDir, linkPath, { recursive: true });
+			} catch {
+				debug(`Copy fallback also failed for ${agentDir}`);
+			}
+		}
+	}
+}
+/**
+* Find the skills source directory shipped with the package.
+* Walks up from the current file to find the package root, then resolves skills/.
+*/
+async function findSkillsSourceDir() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 10; i++) try {
+		await fs.access(path.join(dir, "package.json"));
+		const candidate = path.join(dir, "skills");
+		await fs.access(path.join(candidate, "SKILL.md"));
+		return candidate;
+	} catch {
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+
 //#endregion
 //#region src/helpers/installer.ts
 /**
@@ -1153,7 +1261,8 @@ var Installer = class {
 			this.ensureTsConfig(),
 			this.ensurePrettierConfig(),
 			this.ensureFramerDeclarations(),
-			this.ensurePackageJson()
+			this.ensurePackageJson(),
+			this.ensureSkills()
 		]);
 		Promise.resolve().then(async () => {
 			await this.ensureReact18Types();
@@ -1304,6 +1413,9 @@ declare module "*.json"
 			debug("Created package.json");
 		}
 	}
+	async ensureSkills() {
+		await installSkills(this.projectDir);
+	}
 	async ensureReact18Types() {
 		const reactTypesDir = path.join(this.projectDir, "node_modules/@types/react");
 		const reactFiles = [
@@ -1781,11 +1893,17 @@ async function findOrCreateProjectDir(projectHash, projectName, explicitDir) {
 	if (explicitDir) {
 		const resolved = path.resolve(explicitDir);
 		await fs.mkdir(path.join(resolved, "files"), { recursive: true });
-		return resolved;
+		return {
+			dir: resolved,
+			created: false
+		};
 	}
 	const cwd = process.cwd();
 	const existing = await findExistingProjectDir(cwd, projectHash);
-	if (existing) return existing;
+	if (existing) return {
+		dir: existing,
+		created: false
+	};
 	if (!projectName) throw new Error("Failed to get Project name. Pass --name <project name>.");
 	const dirName = toDirName(projectName);
 	const pkgName = toPackageName(projectName);
@@ -1797,11 +1915,13 @@ async function findOrCreateProjectDir(projectHash, projectName, explicitDir) {
 		version: "1.0.0",
 		private: true,
 		shortProjectHash: shortId,
-		framerProjectHash: projectHash,
 		framerProjectName: projectName
 	};
 	await fs.writeFile(path.join(projectDir, "package.json"), JSON.stringify(pkg, null, 2));
-	return projectDir;
+	return {
+		dir: projectDir,
+		created: true
+	};
 }
 async function findExistingProjectDir(baseDir, projectHash) {
 	if (await matchesProject(path.join(baseDir, "package.json"), projectHash)) return baseDir;
@@ -2231,7 +2351,9 @@ async function executeEffect(effect, context) {
 		case "INIT_WORKSPACE":
 			if (!config.projectDir) {
 				const projectName = config.explicitName ?? effect.projectInfo.projectName;
-				config.projectDir = await findOrCreateProjectDir(config.projectHash, projectName, config.explicitDir);
+				const result = await findOrCreateProjectDir(config.projectHash, projectName, config.explicitDir);
+				config.projectDir = result.dir;
+				config.projectDirCreated = result.created;
 				config.filesDir = `${config.projectDir}/files`;
 				debug(`Files directory: ${config.filesDir}`);
 				await fs.mkdir(config.filesDir, { recursive: true });
@@ -2383,7 +2505,12 @@ async function executeEffect(effect, context) {
 				resetDisconnectState();
 				return [];
 			}
-			success(`Synced ${effect.totalCount} files (${effect.updatedCount} updated, ${effect.unchangedCount} unchanged)`);
+			const relativeDir = config.projectDir ? "./" + (path.relative(process.cwd(), config.projectDir) || ".") : null;
+			if (effect.totalCount === 0 && relativeDir) if (config.projectDirCreated) success(`Created ${relativeDir} folder`);
+			else success(`Syncing to ${relativeDir} folder`);
+			else if (relativeDir && config.projectDirCreated) success(`Synced into ${relativeDir} (${effect.updatedCount} files added)`);
+			else if (relativeDir) success(`Synced into ${relativeDir} (${effect.updatedCount} files updated, ${effect.unchangedCount} unchanged)`);
+			else success(`Synced ${effect.totalCount} files (${effect.updatedCount} updated, ${effect.unchangedCount} unchanged)`);
 			status("Watching for changes...");
 			return [];
 		}
@@ -2444,6 +2571,8 @@ async function start(config) {
 			return;
 		}
 		(async () => {
+			cancelDisconnectMessage();
+			if (!wasRecentlyDisconnected() && !didShowDisconnect()) success(`Connected to ${message.projectName}`);
 			await processEvent({
 				type: "HANDSHAKE",
 				socket: client,
@@ -2460,8 +2589,6 @@ async function start(config) {
 				await installer.initialize();
 				startWatcher();
 			}
-			cancelDisconnectMessage();
-			if (!wasRecentlyDisconnected() && !didShowDisconnect()) success(`Connected to ${message.projectName}`);
 		})();
 	});
 	async function handleMessage(message) {
@@ -2607,7 +2734,7 @@ program.name("framer-code-link").description("Sync Framer code components to you
 		const detected = await getProjectHashFromCwd();
 		if (detected) projectHash = detected;
 		else {
-			console.error("No project ID provided and no existing code-link directory found.");
+			console.error("No Project ID provided and no existing Code Link directory found.");
 			console.error("Copy the command from the Code Link Plugin to get started.");
 			process.exit(1);
 		}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "framer-code-link",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "CLI tool for syncing Framer code components - controller-centric architecture",
   "main": "dist/index.mjs",
   "type": "module",
   "bin": "./dist/index.mjs",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "dev": "NODE_ENV=development tsx src/index.ts",

package/skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: framer-component-best-practices
+description: Best practices for building and improving React code components in Framer, a no-code website builder. Covers property controls, animations, accessibility, and platform constraints. Use when creating, editing, or reviewing Framer components, working with ControlType property controls, or building React components for Framer projects.
+license: MIT
+metadata:
+  author: framer
+  version: "1.0"
+---
+
+# Framer Component Best Practices
+
+Best practices for building and improving React components in Framer with property controls, animations, and accessibility.
+
+## Core Rules
+
+### Component Structure
+
+```tsx
+import { addPropertyControls, ControlType } from "framer";
+import { motion } from "framer-motion"; // NOT from "framer"
+
+interface MyComponentProps {
+  /* typed props */
+}
+
+/**
+ * @framerSupportedLayoutWidth any-prefer-fixed
+ * @framerSupportedLayoutHeight any-prefer-fixed
+ */
+export default function MyComponent(props: MyComponentProps) {
+  // component
+}
+
+addPropertyControls(MyComponent, {
+  /* controls */
+});
+```
+
+### Platform Constraints
+
+These will cause errors if violated:
+
+1. **Single file, default export** - Use named `function` syntax (not arrow functions), no named exports
+2. **Imports** - Only `react`, `react-dom`, `framer`, `framer-motion`. Import `motion` from `"framer-motion"`, not `"framer"`
+3. **Position** - Use `position: relative` on the root element, never `fixed`
+4. **SSR** - Guard `window`/`document` access: `if (typeof window !== "undefined")`
+5. **Annotations** - Include `@framerSupportedLayoutWidth/Height` in a `/** */` block comment immediately above the component function
+6. **Types** - Provide a typed props interface (e.g. `MyComponentProps`). Avoid NodeJS types like `Timeout` — use `number` instead
+
+### Layout Annotations
+
+| Content           | Width              | Height             |
+| ----------------- | ------------------ | ------------------ |
+| No intrinsic size | `fixed`            | `fixed`            |
+| Text/auto-sizing  | `auto`             | `auto`             |
+| Flexible          | `any-prefer-fixed` | `any-prefer-fixed` |
+
+Detect auto vs fixed sizing: check if `style.width` or `style.height` is `"100%"`.
+
+### Property Controls
+
+To make components configurable in Framer's properties panel, add property controls:
+
+- To make colors customizable, use `ControlType.Color`. Reuse the same prop for elements sharing a color.
+- To make text styling customizable, use `ControlType.Font` with `controls: "extended"` and `defaultFontType: "sans-serif"`.
+- For images, use `ControlType.ResponsiveImage`. Set defaults in the component body via destructuring (the control doesn't support `defaultValue`).
+- Provide a `defaultValue` for every prop so components render correctly in the Framer canvas. Include at least one item in `ControlType.Array` controls.
+- `ComponentName.defaultProps` is not supported in Framer — use `defaultValue` on the property control instead.
+- Use `hidden` for conditional visibility: `hidden: (props) => !props.showFeature`
+- Prefer sliders over steppers unless step values are large.
+- Keep controls focused — make key elements configurable, hardcode the rest.
+- See [Property Control Guide](references/PROPERTY_CONTROL_GUIDE.md) for detailed patterns, font styling rules, and recommended default values.
+
+### Image Defaults (in component body)
+
+```tsx
+const {
+  image = {
+    src: "https://framerusercontent.com/images/GfGkADagM4KEibNcIiRUWlfrR0.jpg",
+    alt: "Default",
+  },
+} = props;
+```
+
+### Animation Performance
+
+```tsx
+import { useIsStaticRenderer } from "framer";
+import { useInView } from "framer-motion";
+
+const isStatic = useIsStaticRenderer();
+const ref = useRef(null);
+const isInView = useInView(ref);
+
+if (isStatic) return <StaticPreview />; // Show useful static state
+// Pause animations when out of viewport
+```
+
+- For very complex animations, consider WebGL instead of `framer-motion`.
+- Static preview should include visual effects, not just text.
+- Wrapping state updates in `startTransition()` prevents UI blocking and keeps interactions smooth.
+
+### Text
+
+- For auto-sized components with text, apply `width: max-content` or `minWidth: max-content` to prevent text from collapsing.
+
+### Common Errors
+
+- WebGL cross-origin: handle `SecurityError: Failed to execute 'texImage2D'` for cross-origin images.
+- Inverted Y-axis: check if WebGL images render upside down and accommodate.
+
+### Accessibility
+
+- `aria` roles on interactive elements
+- Semantic HTML (`<nav>`, `<article>`, `<section>`)
+- `alt=""` on decorative images
+- 4.5:1 color contrast
+
+## Term Interpretation
+
+- "responsive" → width/height 100%
+- "modern" → 8px radius, 16px spacing, subtle shadows
+- "minimal" → limited colors, whitespace
+- "interactive" → hover/active states
+- "accessible" → ARIA, semantic HTML
+- "props"/"properties" → Framer property controls
+
+## Reference Files
+
+- [Property Controls](references/PROPERTY_CONTROLS.md) - All ControlType documentation with examples
+- [Property Control Types](references/PROPERTY_CONTROL_TYPES.md) - TypeScript interfaces for all control types
+- [Property Control Guide](references/PROPERTY_CONTROL_GUIDE.md) - Font patterns, styling rules, and recommended default values
+- [Example Components](references/EXAMPLES.md) - Cookie banner, image compare, sticky notes, twemoji