@ivannxbt/ai-config 0.1.0

package/.agents/skills/framer-code-components-overrides/references/property-controls.md

@@ -0,0 +1,241 @@
+# Property Controls Reference
+
+## Control Types
+
+### String
+```typescript
+text: {
+    type: ControlType.String,
+    title: "Text",
+    defaultValue: "Hello",
+    placeholder: "Enter text...",
+    displayTextArea: true, // For multiline
+}
+```
+
+### Number
+```typescript
+value: {
+    type: ControlType.Number,
+    title: "Value",
+    defaultValue: 50,
+    min: 0,
+    max: 100,
+    step: 1,
+    unit: "px",
+    displayStepper: true,
+}
+```
+
+### Boolean
+```typescript
+enabled: {
+    type: ControlType.Boolean,
+    title: "Enabled",
+    defaultValue: true,
+    enabledTitle: "On",
+    disabledTitle: "Off",
+}
+```
+
+### Color
+```typescript
+color: {
+    type: ControlType.Color,
+    title: "Color",
+    defaultValue: "#09f",
+}
+```
+
+### Enum (Dropdown or Segmented)
+```typescript
+mode: {
+    type: ControlType.Enum,
+    title: "Mode",
+    defaultValue: "auto",
+    options: ["auto", "manual", "disabled"],
+    optionTitles: ["Auto", "Manual", "Disabled"],
+    displaySegmentedControl: true, // false for dropdown
+}
+```
+
+### Image
+```typescript
+image: {
+    type: ControlType.Image,
+    title: "Image",
+}
+```
+
+Returns URL string. For previews in the control panel, use `ControlType.ResponsiveImage`.
+
+### File
+```typescript
+video: {
+    type: ControlType.File,
+    title: "Video",
+    allowedFileTypes: ["mp4", "webm"],
+}
+```
+
+### Font (Extended)
+```typescript
+font: {
+    type: ControlType.Font,
+    title: "Font",
+    controls: "extended",
+    defaultValue: {
+        fontFamily: "Inter",
+        fontWeight: 500,
+        fontSize: 16,
+        lineHeight: "1.5em",
+    },
+}
+```
+
+**Critical**: Always spread the entire font object in styles: `...props.font`
+
+### Transition
+```typescript
+transition: {
+    type: ControlType.Transition,
+    title: "Transition",
+    defaultValue: { duration: 0.5 },
+}
+```
+
+### ComponentInstance
+```typescript
+icon: {
+    type: ControlType.ComponentInstance,
+    title: "Icon",
+}
+```
+
+Accepts a component from the canvas.
+
+### Array
+```typescript
+items: {
+    type: ControlType.Array,
+    title: "Items",
+    maxCount: 10,
+    control: {
+        type: ControlType.String,
+    },
+}
+```
+
+### Array with Image Preview
+```typescript
+images: {
+    type: ControlType.Array,
+    title: "Images",
+    control: {
+        type: ControlType.Object,
+        controls: {
+            image: {
+                type: ControlType.ResponsiveImage,
+            },
+        },
+    },
+}
+```
+
+### Object (Grouped Controls)
+```typescript
+settings: {
+    type: ControlType.Object,
+    title: "Settings",
+    controls: {
+        opacity: { type: ControlType.Number, defaultValue: 1 },
+        color: { type: ControlType.Color, defaultValue: "#fff" },
+    },
+}
+```
+
+## Conditional Visibility
+
+Hide controls based on other prop values:
+
+```typescript
+advancedMode: {
+    type: ControlType.Boolean,
+    defaultValue: false,
+},
+advancedSetting: {
+    type: ControlType.Number,
+    hidden: (props) => !props.advancedMode,
+},
+```
+
+## Markdown Descriptions
+
+```typescript
+setting: {
+    type: ControlType.Number,
+    description: "Controls the *intensity*.\n\n[Learn more](https://example.com)",
+}
+```
+
+## Default Props Requirement
+
+Property Controls only affect canvas. Always define `defaultProps` for:
+- Preventing runtime errors
+- Components instantiated from code
+- Initial render before controls apply
+
+```typescript
+MyComponent.defaultProps = {
+    text: "Default",
+    color: "#000",
+    font: {
+        fontFamily: "Inter",
+        fontWeight: 500,
+        fontSize: 16,
+    },
+}
+```
+
+## Common Patterns
+
+### Mode-Dependent Controls
+```typescript
+addPropertyControls(Component, {
+    mode: {
+        type: ControlType.Enum,
+        options: ["image", "video"],
+        defaultValue: "image",
+    },
+    image: {
+        type: ControlType.Image,
+        hidden: (props) => props.mode !== "image",
+    },
+    video: {
+        type: ControlType.File,
+        allowedFileTypes: ["mp4"],
+        hidden: (props) => props.mode !== "video",
+    },
+})
+```
+
+### Nested Object with Conditional
+```typescript
+progressOptions: {
+    type: ControlType.Object,
+    title: "Progress",
+    controls: {
+        showProgress: {
+            type: ControlType.Boolean,
+            defaultValue: false,
+        },
+        progressFont: {
+            type: ControlType.Font,
+            controls: "extended",
+            hidden: (props) => !props.showProgress,
+        },
+    },
+}
+```
+
+Note: In nested objects, `hidden` receives the parent object, not root props.

package/.agents/skills/framer-code-components-overrides/references/webgl-shaders.md

@@ -0,0 +1,207 @@
+# WebGL Shaders in Framer
+
+## Basic Setup
+
+```typescript
+import { useEffect, useRef } from "react"
+
+export default function ShaderComponent(props) {
+    const canvasRef = useRef(null)
+
+    useEffect(() => {
+        const canvas = canvasRef.current
+        const gl = canvas.getContext("webgl", { alpha: true })
+
+        if (!gl) {
+            console.error("WebGL not supported")
+            return
+        }
+
+        // Setup and render loop here
+
+        return () => {
+            // Cleanup
+        }
+    }, [])
+
+    return (
+        <canvas
+            ref={canvasRef}
+            style={{
+                width: "100%",
+                height: "100%",
+                display: "block",
+            }}
+        />
+    )
+}
+```
+
+## Transparency Support
+
+Four requirements for transparent shaders:
+
+### 1. Alpha-enabled Context
+```typescript
+const gl = canvas.getContext("webgl", { alpha: true })
+```
+
+### 2. Blending Configuration
+```typescript
+gl.enable(gl.BLEND)
+gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
+```
+
+### 3. Transparent Clear Color
+```typescript
+gl.clearColor(0.0, 0.0, 0.0, 0.0)
+gl.clear(gl.COLOR_BUFFER_BIT)
+```
+
+### 4. Fragment Shader Alpha Handling
+```glsl
+// Accumulate alpha in fragment shader
+cl.a += smoothstep(2.5, 0.0, rz) * 0.1;
+
+// Limit maximum opacity
+color.a = min(color.a, 0.7);
+```
+
+## Shader Compilation Safety
+
+**Always check shader compilation before attaching:**
+
+```typescript
+function createShader(gl, type, source) {
+    const shader = gl.createShader(type)
+    gl.shaderSource(shader, source)
+    gl.compileShader(shader)
+
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        console.error("Shader compilation failed:", gl.getShaderInfoLog(shader))
+        gl.deleteShader(shader)
+        return null
+    }
+    return shader
+}
+
+function createProgram(gl, vertexShader, fragmentShader) {
+    // Guard against null shaders
+    if (!vertexShader || !fragmentShader) return null
+
+    const program = gl.createProgram()
+    gl.attachShader(program, vertexShader)
+    gl.attachShader(program, fragmentShader)
+    gl.linkProgram(program)
+
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        console.error("Program linking failed:", gl.getProgramInfoLog(program))
+        gl.deleteProgram(program)
+        return null
+    }
+    return program
+}
+
+// Usage with null checks
+const vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSource)
+if (!vertexShader) return
+
+const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSource)
+if (!fragmentShader) return
+
+const program = createProgram(gl, vertexShader, fragmentShader)
+if (!program) return
+```
+
+## Canvas Resize Handling
+
+```typescript
+function resizeCanvasToDisplaySize(canvas) {
+    const displayWidth = canvas.clientWidth
+    const displayHeight = canvas.clientHeight
+
+    if (canvas.width !== displayWidth || canvas.height !== displayHeight) {
+        canvas.width = displayWidth
+        canvas.height = displayHeight
+        return true
+    }
+    return false
+}
+
+// In render loop
+function render() {
+    resizeCanvasToDisplaySize(gl.canvas)
+    gl.viewport(0, 0, gl.canvas.width, gl.canvas.height)
+
+    // Draw calls...
+
+    requestAnimationFrame(render)
+}
+```
+
+## Uniform Updates
+
+```typescript
+const resolutionLocation = gl.getUniformLocation(program, "resolution")
+const timeLocation = gl.getUniformLocation(program, "time")
+
+let startTime = performance.now()
+
+function render() {
+    gl.useProgram(program)
+    gl.uniform2f(resolutionLocation, gl.canvas.width, gl.canvas.height)
+    gl.uniform1f(timeLocation, (performance.now() - startTime) * 0.001)
+
+    // Draw...
+    requestAnimationFrame(render)
+}
+```
+
+## Cleanup Pattern
+
+```typescript
+useEffect(() => {
+    let animationId
+
+    // Setup...
+
+    function render() {
+        // Draw...
+        animationId = requestAnimationFrame(render)
+    }
+    render()
+
+    return () => {
+        if (animationId) {
+            cancelAnimationFrame(animationId)
+        }
+        // Additional cleanup: delete shaders, programs, buffers
+    }
+}, [])
+```
+
+## Canvas Positioning for Effects
+
+For effects that need to extend beyond component bounds:
+
+```typescript
+const safetyMargin = 100
+
+// Canvas larger than container
+const canvasWidth = containerWidth + safetyMargin * 2
+const canvasHeight = containerHeight + safetyMargin * 2
+
+// Position with negative offset
+<canvas
+    style={{
+        position: "absolute",
+        top: -safetyMargin,
+        left: -safetyMargin,
+        width: canvasWidth,
+        height: canvasHeight,
+        pointerEvents: "none",
+    }}
+/>
+```
+
+Container needs `overflow: visible` for this pattern.

package/.agents/skills/framework-selection/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: framework-selection
+description: "INVOKE THIS SKILL at the START of any LangChain/LangGraph/Deep Agents project, before writing any agent code. Determines which framework layer is right for the task: LangChain, LangGraph, Deep Agents, or a combination. Must be consulted before other agent skills."
+---
+
+<overview>
+LangChain, LangGraph, and Deep Agents are **layered**, not competing choices. Each builds on the one below it:
+
+```
+┌─────────────────────────────────────────┐
+│              Deep Agents                │  ← highest level: batteries included
+│   (planning, memory, skills, files)     │
+├─────────────────────────────────────────┤
+│               LangGraph                 │  ← orchestration: graphs, loops, state
+│    (nodes, edges, state, persistence)   │
+├─────────────────────────────────────────┤
+│               LangChain                 │  ← foundation: models, tools, chains
+│      (models, tools, prompts, RAG)      │
+└─────────────────────────────────────────┘
+```
+
+Picking a higher layer does not cut you off from lower layers — you can use LangGraph graphs inside Deep Agents, and LangChain primitives inside both.
+
+> **This skill should be loaded at the top of any project before selecting other skills or writing agent code.** The framework you choose dictates which other skills to invoke next.
+</overview>
+
+---
+
+## Decision Guide
+
+<decision-table>
+
+Answer these questions in order:
+
+| Question | Yes → | No → |
+|----------|-------|-------|
+| Does the task require breaking work into sub-tasks, managing files across a long session, persistent memory, or loading on-demand skills? | **Deep Agents** | ↓ |
+| Does the task require complex control flow — loops, dynamic branching, parallel workers, human-in-the-loop, or custom state? | **LangGraph** | ↓ |
+| Is this a single-purpose agent that takes input, runs tools, and returns a result? | **LangChain** (`create_agent`) | ↓ |
+| Is this a pure model call, chain, or retrieval pipeline with no agent loop? | **LangChain** (LCEL / chain) | — |
+
+</decision-table>
+
+---
+
+## Framework Profiles
+
+<langchain-profile>
+
+### LangChain — Use when the task is focused and self-contained
+
+**Best for:**
+- Single-purpose agents that use a fixed set of tools
+- RAG pipelines and document Q&A
+- Model calls, prompt templates, output parsing
+- Quick prototypes where agent logic is simple
+
+**Not ideal when:**
+- The agent needs to plan across many steps
+- State needs to persist across multiple sessions
+- Control flow is conditional or iterative
+
+**Skills to invoke next:** `langchain-models`, `langchain-rag`, `langchain-middleware`
+
+</langchain-profile>
+
+<langgraph-profile>
+
+### LangGraph — Use when you need to own the control flow
+
+**Best for:**
+- Agents with branching logic or loops (e.g. retry-until-correct, reflection)
+- Multi-step workflows where different paths depend on intermediate results
+- Human-in-the-loop approval at specific steps
+- Parallel fan-out / fan-in (map-reduce patterns)
+- Persistent state across invocations within a session
+
+**Not ideal when:**
+- You want planning, file management, and subagent delegation handled for you (use Deep Agents instead)
+- The workflow is straightforward enough for a simple agent
+
+**Skills to invoke next:** `langgraph-fundamentals`, `langgraph-human-in-the-loop`, `langgraph-persistence`
+
+</langgraph-profile>
+
+<deep-agents-profile>
+
+### Deep Agents — Use when the task is open-ended and multi-dimensional
+
+**Best for:**
+- Long-running tasks that require breaking work into a todo list
+- Agents that need to read, write, and manage files across a session
+- Delegating subtasks to specialized subagents
+- Loading domain-specific skills on demand
+- Persistent memory that survives across multiple sessions
+
+**Not ideal when:**
+- The task is simple enough for a single-purpose agent
+- You need precise, hand-crafted control over every graph edge (use LangGraph directly)
+
+**Middleware — built-in and extensible:**
+
+Deep Agents ships with a built-in middleware layer out of the box — you configure it, you don't implement it. The following come pre-wired; you can also add your own on top:
+
+| Middleware | What it provides | Always on? |
+|------------|-----------------|------------|
+| `TodoListMiddleware` | `write_todos` tool — agent plans and tracks multi-step tasks | ✓ |
+| `FilesystemMiddleware` | `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` tools | ✓ |
+| `SubAgentMiddleware` | `task` tool — delegate work to named subagents | ✓ |
+| `SkillsMiddleware` | Load SKILL.md files on demand from a skills directory | Opt-in |
+| `MemoryMiddleware` | Long-term memory across sessions via a `Store` instance | Opt-in |
+| `HumanInTheLoopMiddleware` | Interrupt and request human approval before sensitive tool calls | Opt-in |
+
+**Skills to invoke next:** `deep-agents-core`, `deep-agents-memory`, `deep-agents-orchestration`
+
+</deep-agents-profile>
+
+---
+
+## Mixing Layers
+
+<mixing-layers>
+Because the frameworks are layered, they can be combined in the same project. The most common pattern is using Deep Agents as the top-level orchestrator while dropping down to LangGraph for specialized subagents.
+
+### When to mix
+
+| Scenario | Recommended pattern |
+|----------|---------------------|
+| Main agent needs planning + memory, but one subtask requires precise graph control | Deep Agents orchestrator → LangGraph subagent |
+| Specialized pipeline (e.g. RAG, reflection loop) is called by a broader agent | LangGraph graph wrapped as a tool or subagent |
+| High-level coordination but low-level graph for a specific domain | Deep Agents + LangGraph compiled graph as a subagent |
+
+### How it works in practice
+
+A LangGraph compiled graph can be registered as a subagent inside Deep Agents. This means you can build a tightly-controlled LangGraph workflow (e.g. a retrieval-and-verify loop) and hand it off to the Deep Agents `task` tool as a named subagent — the Deep Agents orchestrator delegates to it without caring about its internal graph structure.
+
+LangChain tools, chains, and retrievers can be used freely inside both LangGraph nodes and Deep Agents tools — they are the shared building blocks at every level.
+
+</mixing-layers>
+
+---
+
+## Quick Reference
+
+<quick-reference>
+
+| | LangChain | LangGraph | Deep Agents |
+|---|-----------|-----------|-------------|
+| **Control flow** | Fixed (tool loop) | Custom (graph) | Managed (middleware) |
+| **Middleware layer** | Callbacks only | ✗ None | ✓ Explicit, configurable |
+| **Planning** | ✗ | Manual | ✓ TodoListMiddleware |
+| **File management** | ✗ | Manual | ✓ FilesystemMiddleware |
+| **Persistent memory** | ✗ | With checkpointer | ✓ MemoryMiddleware |
+| **Subagent delegation** | ✗ | Manual | ✓ SubAgentMiddleware |
+| **On-demand skills** | ✗ | ✗ | ✓ SkillsMiddleware |
+| **Human-in-the-loop** | ✗ | Manual interrupt | ✓ HumanInTheLoopMiddleware |
+| **Custom graph edges** | ✗ | ✓ Full control | Limited |
+| **Setup complexity** | Low | Medium | Low |
+| **Flexibility** | Medium | High | Medium |
+
+> **Middleware is a concept specific to LangChain (callbacks) and Deep Agents (explicit middleware layer). LangGraph has no middleware — you wire behavior directly into nodes and edges.**
+
+</quick-reference>