fusee-framework 1.3.0 → 1.4.0

package/README.md

@@ -1,5 +1,5 @@
 # Fusée Framework 🚀
-**v1.3.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
+**v1.4.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
 
 Fusée is a custom, high-performance fine-grained reactive JavaScript framework built for speed and simplicity. It features a recursive, non-greedy compiler, a signals-based reactivity engine, Dependency Injection for components and a comprehensive CLI for instant application scaffolding.
 

package/app/composables/demo.js

@@ -0,0 +1,29 @@
+import { defineComposable, assertSetupContext, signal, computed, onMount, onUnmount } from '../../framework/index.js'
+
+// ─── counterLogic ─────────────────────────────────────────────────────────────
+export const counterLogic = defineComposable((initial = 0, step = 1) => {
+    const count = signal(initial)
+    const doubled = computed(() => count() * 2)
+    const isEven = computed(() => count() % 2 === 0)
+
+    const increment = () => count(count() + step)
+    const decrement = () => count(count() - step)
+    const reset = () => count(initial)
+
+    return { count, doubled, isEven, increment, decrement, reset }
+})
+
+// ─── mouseTracker ─────────────────────────────────────────────────────────────
+export const mouseTracker = defineComposable(() => {
+    assertSetupContext('mouseTracker')
+
+    const x = signal(0)
+    const y = signal(0)
+
+    const onMove = (e) => { x(e.clientX); y(e.clientY) }
+
+    onMount(() => window.addEventListener('mousemove', onMove))
+    onUnmount(() => window.removeEventListener('mousemove', onMove))
+
+    return { x, y }
+})

package/app/composables/demo.ts

@@ -0,0 +1,30 @@
+import { defineComposable, assertSetupContext, signal, computed, onMount, onUnmount } from '../../framework/index.js'
+
+export const counterLogic = defineComposable((initial: number = 0, step: number = 1) => {
+    const count   = signal(initial)
+    const doubled = computed(() => count() * 2)
+    const isEven  = computed(() => count() % 2 === 0)
+
+    const increment = () => count(count() + step)
+    const decrement = () => count(count() - step)
+    const reset     = () => count(initial)
+
+    return { count, doubled, isEven, increment, decrement, reset }
+})
+
+export const mouseTracker = defineComposable(() => {
+    assertSetupContext('mouseTracker')
+
+    const x = signal(0)
+    const y = signal(0)
+
+    const onMove = (e: MouseEvent) => { 
+        x(e.clientX)
+        y(e.clientY) 
+    }
+
+    onMount(() => window.addEventListener('mousemove', onMove))
+    onUnmount(() => window.removeEventListener('mousemove', onMove))
+
+    return { x, y }
+})

package/app/composables/useFetch.js

@@ -0,0 +1,53 @@
+import { defineComposable, signal, effect } from '../../framework/index.js'
+
+/**
+ * @template T
+ * @param {string | (() => string)} urlOrSignal
+ * @param {{ immediate?: boolean, transform?: (raw: any) => T }} [options]
+ */
+export const useFetch = defineComposable((urlOrSignal, options = {}) => {
+    const { immediate = true, transform = null } = options
+
+    const data    = signal(null)
+    const loading = signal(false)
+    const error   = signal(null)
+
+    let controller = null
+
+    const execute = () => {
+        const url = typeof urlOrSignal === 'function' ? urlOrSignal() : urlOrSignal
+        if (!url) return
+
+        if (controller) controller.abort()
+        controller = new AbortController()
+
+        loading(true)
+        error(null)
+
+        fetch(url, { signal: controller.signal })
+            .then(res => {
+                if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`)
+                return res.json()
+            })
+            .then(raw => {
+                data(transform ? transform(raw) : raw)
+                loading(false)
+            })
+            .catch(err => {
+                if (err.name === 'AbortError') return
+                error(err.message ?? String(err))
+                loading(false)
+            })
+    }
+
+    if (typeof urlOrSignal === 'function') {
+        effect(() => {
+            urlOrSignal()
+            execute()
+        })
+    } else if (immediate) {
+        execute()
+    }
+
+    return { data, loading, error, refetch: execute }
+})

package/app/composables/useFetch.ts

@@ -0,0 +1,63 @@
+import { defineComposable, signal, effect } from '../../framework/index.js'
+
+export interface FetchOptions<T> {
+    immediate?: boolean
+    transform?: (raw: any) => T
+}
+
+export interface FetchResult<T> {
+    data:    Signal<T | null>
+    loading: Signal<boolean>
+    error:   Signal<string | null>
+    refetch: () => void
+}
+
+export const useFetch = defineComposable(<T = any>(
+    urlOrSignal: string | (() => string), 
+    options: FetchOptions<T> = {}
+): FetchResult<T> => {
+    const { immediate = true, transform = null } = options
+
+    const data    = signal<T | null>(null)
+    const loading = signal(false)
+    const error   = signal<string | null>(null)
+
+    let controller: AbortController | null = null
+
+    const execute = () => {
+        const url = typeof urlOrSignal === 'function' ? urlOrSignal() : urlOrSignal
+        if (!url) return
+
+        if (controller) controller.abort()
+        controller = new AbortController()
+
+        loading(true)
+        error(null)
+
+        fetch(url, { signal: controller.signal })
+            .then(res => {
+                if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`)
+                return res.json()
+            })
+            .then(raw => {
+                data(transform ? transform(raw) : raw)
+                loading(false)
+            })
+            .catch(err => {
+                if (err.name === 'AbortError') return
+                error(err.message ?? String(err))
+                loading(false)
+            })
+    }
+
+    if (typeof urlOrSignal === 'function') {
+        effect(() => {
+            urlOrSignal()
+            execute()
+        })
+    } else if (immediate) {
+        execute()
+    }
+
+    return { data, loading, error, refetch: execute }
+})

package/app/composables/useLocalStorage.js

@@ -0,0 +1,31 @@
+import { defineComposable, signal, effect } from '../../framework/index.js'
+
+/**
+ * @template T
+ * @param {string} key
+ * @param {T}      defaultValue
+ */
+export const useLocalStorage = defineComposable((key, defaultValue = null) => {
+    const stored = localStorage.getItem(key)
+    let initial
+
+    try {
+        initial = stored !== null ? JSON.parse(stored) : defaultValue
+    } catch {
+        initial = defaultValue
+        localStorage.removeItem(key)
+    }
+
+    const value = signal(initial)
+
+    effect(() => {
+        const current = value()
+        if (current === null || current === undefined) {
+            localStorage.removeItem(key)
+        } else {
+            localStorage.setItem(key, JSON.stringify(current))
+        }
+    })
+
+    return value
+})

package/app/composables/useLocalStorage.ts

@@ -0,0 +1,26 @@
+import { defineComposable, signal, effect } from '../../framework/index.js'
+
+export const useLocalStorage = defineComposable(<T>(key: string, defaultValue: T | null = null): Signal<T | null> => {
+    const stored = localStorage.getItem(key)
+    let initial: T | null
+
+    try {
+        initial = stored !== null ? JSON.parse(stored) : defaultValue
+    } catch {
+        initial = defaultValue
+        localStorage.removeItem(key)
+    }
+
+    const value = signal<T | null>(initial)
+
+    effect(() => {
+        const current = value()
+        if (current === null || current === undefined) {
+            localStorage.removeItem(key)
+        } else {
+            localStorage.setItem(key, JSON.stringify(current))
+        }
+    })
+
+    return value
+})

package/app/main.js

@@ -1,6 +1,22 @@
 import { createRouter, mountOutlet, defineAsyncComponent } from '../framework/index.js'
 import { Loading } from './components/Loading.js'
 
+directive('focus', {
+    mounted(el) {
+        el.focus()
+    }
+})
+
+directive('highlight', {
+    mounted(el, binding) {
+        el.style.backgroundColor = binding.value || '#ffff0033'
+        el.style.transition = 'background-color 0.3s'
+    },
+    updated(el, binding) {
+        el.style.backgroundColor = binding.value || '#ffff0033'
+    }
+})
+
 const routes = [
     { 
         path: '/', 
@@ -30,6 +46,13 @@ const routes = [
             loadingComponent: Loading
         }) 
     },
+    {
+        path: '/composables',
+        component: defineAsyncComponent({
+            loader: () => import('./routes/TestComposables.js'),
+            loadingComponent: Loading
+        })
+    },
 ]
 
 createRouter(routes)

package/app/main.ts

@@ -2,35 +2,58 @@ import { createRouter, mountOutlet, defineAsyncComponent } from '../framework/in
 import type { Route } from '../framework/types/index.js'
 import { Loading } from './components/Loading.js'
 
+directive('focus', {
+    mounted(el) {
+        el.focus()
+    }
+})
+
+directive('highlight', {
+    mounted(el, binding) {
+        el.style.backgroundColor = binding.value || '#ffff0033'
+        el.style.transition = 'background-color 0.3s'
+    },
+    updated(el, binding) {
+        el.style.backgroundColor = binding.value || '#ffff0033'
+    }
+})
+
 const routes: Route[] = [
     { 
         path: '/', 
         component: defineAsyncComponent({
-            loader: () => import('./routes/Home.js'),
+            loader: () => import('./routes/Home.ts'),
             loadingComponent: Loading
         }) 
     },
     { 
         path: '/about', 
         component: defineAsyncComponent({
-            loader: () => import('./routes/About.js'),
+            loader: () => import('./routes/About.ts'),
             loadingComponent: Loading
         }) 
     },
     { 
         path: '/test-for', 
         component: defineAsyncComponent({
-            loader: () => import('./routes/TestFor.js'),
+            loader: () => import('./routes/TestFor.ts'),
             loadingComponent: Loading
         }) 
     },
     { 
         path: '/dynamic', 
         component: defineAsyncComponent({
-            loader: () => import('./routes/TestDynamic.js'),
+            loader: () => import('./routes/TestDynamic.ts'),
             loadingComponent: Loading
         }) 
     },
+    {
+        path: '/composables',
+        component: defineAsyncComponent({
+            loader: () => import('./routes/TestComposables.ts'),
+            loadingComponent: Loading
+        })
+    },
 ]
 
 createRouter(routes)

package/app/routes/TestComposables.js

@@ -0,0 +1,158 @@
+import { counterLogic, mouseTracker } from '../composables/demo.js'
+import { useFetch } from '../composables/useFetch.js'
+import { useLocalStorage } from '../composables/useLocalStorage.js'
+
+export const TestComposables = defineComponent({
+    setup() {
+        // ── 1. counterLogic — pure signal composable, no context needed ──────
+        const counter = counterLogic(0, 1)
+        const bigCounter = counterLogic(100, 10)
+
+        // ── 2. mouseTracker — lifecycle composable (needs setup context) ─────
+        const mouse = mouseTracker()
+
+        // ── 3. useLocalStorage — persists across page reloads ────────────────
+        const theme = useLocalStorage('demo-theme', 'dark')
+        const nickname = useLocalStorage('demo-nickname', '')
+
+        const toggleTheme = () => theme(theme() === 'dark' ? 'light' : 'dark')
+
+        // ── 4. useFetch — reactive data fetching ─────────────────────────────
+        const { data: posts, loading, error } = useFetch(
+            'https://jsonplaceholder.typicode.com/posts?_limit=3'
+        )
+        // ── 5. Custom Directives Test ────────────────────────────────────────
+        const hColor = signal('#8b8bff33')
+        const colors = ['#8b8bff33', '#10b98133', '#f59e0b33', '#ef444433']
+        let colorIdx = 0
+        const nextColor = () => hColor(colors[++colorIdx % colors.length])
+
+        return {
+            hColor,
+            nextColor,
+
+            // counter
+            count: counter.count,
+            doubled: counter.doubled,
+            isEven: counter.isEven,
+            increment: counter.increment,
+            decrement: counter.decrement,
+            reset: counter.reset,
+
+            // big counter
+            bigCount: bigCounter.count,
+            bigIncrement: bigCounter.increment,
+            bigDecrement: bigCounter.decrement,
+
+            // mouse
+            mouseX: mouse.x,
+            mouseY: mouse.y,
+
+            // localStorage
+            theme,
+            nickname,
+            toggleTheme,
+
+            // fetch
+            posts,
+            loading,
+            error,
+
+            template: `
+                <div class="page">
+                    <h1>🧩 Composables Demo</h1>
+                    <p style="color:#888; margin-bottom: 2rem;">
+                        Each section below is powered by a <code style="color:#ff3333">defineComposable()</code> function.
+                        No naming rules — just reactive logic.
+                    </p>
+
+                    <!-- ── 1. counterLogic ─────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>📦 counterLogic(0, step=1)</h2>
+                        <p class="demo-desc">Pure signal composable — works without setup() context.</p>
+                        <div class="counter-display">
+                            <span class="big-num" :class="isEven ? 'even' : 'odd'">{{ count }}</span>
+                            <span class="derived-label">× 2 = {{ doubled }}</span>
+                        </div>
+                        <div class="btn-row">
+                            <button @click="decrement" class="cmp-btn minus">−</button>
+                            <button @click="reset"     class="cmp-btn reset">↺</button>
+                            <button @click="increment" class="cmp-btn plus">+</button>
+                        </div>
+                        <p class="badge" :class="isEven ? 'badge-blue' : 'badge-red'">{{ isEven ? 'Even' : 'Odd' }}</p>
+                    </section>
+
+                    <!-- ── 1b. Second independent counter (step=10) ───────────── -->
+                    <section class="demo-card">
+                        <h2>📦 counterLogic(100, step=10)</h2>
+                        <p class="demo-desc">Same composable, different instance. Fully isolated state.</p>
+                        <div class="counter-display">
+                            <span class="big-num">{{ bigCount }}</span>
+                        </div>
+                        <div class="btn-row">
+                            <button @click="bigDecrement" class="cmp-btn minus">−10</button>
+                            <button @click="bigIncrement" class="cmp-btn plus">+10</button>
+                        </div>
+                    </section>
+
+                    <!-- ── 2. mouseTracker ────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>🖱️ mouseTracker()</h2>
+                        <p class="demo-desc">Lifecycle composable — registers window listener on mount, cleans up on unmount.</p>
+                        <div class="mouse-display">
+                            <span>X: <strong>{{ mouseX }}</strong></span>
+                            <span>Y: <strong>{{ mouseY }}</strong></span>
+                        </div>
+                    </section>
+
+                    <!-- ── 3. useLocalStorage ─────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>💾 useLocalStorage()</h2>
+                        <p class="demo-desc">State persists across page reloads. Try changing the nickname, then refresh.</p>
+                        <div style="margin-bottom: 12px;">
+                            <input f-model="nickname"
+                                   class="cmp-input"
+                                   placeholder="Your nickname…" />
+                            <p style="margin-top: 8px; color: #888; font-size: 0.85rem;">
+                                Stored: <strong style="color:#ff3333">{{ nickname || '(empty)' }}</strong>
+                            </p>
+                        </div>
+                        <button @click="toggleTheme" class="cmp-btn reset">
+                            Theme: {{ theme }}
+                        </button>
+                    </section>
+
+                    <!-- ── 4. useFetch ────────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>🌐 useFetch()</h2>
+                        <p class="demo-desc">Fetches from JSONPlaceholder. Loading state handled reactively.</p>
+                        <div f-if="loading">
+                            <p style="color: #888;">⏳ Loading posts…</p>
+                        </div>
+                        <div f-elif="error">
+                            <p style="color: #ff6b6b;">❌ {{ error }}</p>
+                        </div>
+                        <div f-else>
+                            <div f-for="post in posts" style="margin-bottom: 10px; padding: 10px; background:#1a1a24; border-radius:6px; border-left: 3px solid #ff3333;">
+                                <strong style="color:#ff9999">{{ post.title }}</strong>
+                                <p style="margin-top: 4px; font-size: 0.8rem; color: #666;">{{ post.body }}</p>
+                            </div>
+                        </div>
+                    </section>
+
+                    <!-- ── 6. Custom Directives ────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>🛠️ Custom Directives</h2>
+                        <p class="demo-desc">Testing <code>f-focus</code> and <code>f-highlight</code>.</p>
+                        
+                        <div f-highlight="hColor" style="padding: 15px; border-radius: 8px; margin-bottom: 10px;">
+                            <input f-focus class="cmp-input" placeholder="I have f-focus!" />
+                        </div>
+                        
+                        <button @click="nextColor" class="cmp-btn plus">Change Highlight Color</button>
+                    </section>
+                </div>
+            `
+        }
+    }
+})

package/app/routes/TestComposables.ts

@@ -0,0 +1,158 @@
+import { defineComponent } from '../../framework/index.js'
+import { counterLogic, mouseTracker } from '../composables/demo.js'
+import { useFetch } from '../composables/useFetch.js'
+import { useLocalStorage } from '../composables/useLocalStorage.js'
+
+export const TestComposables = defineComponent({
+    setup() {
+        // ── 1. counterLogic — pure signal composable, no context needed ──────
+        const counter = counterLogic(0, 1)
+        const bigCounter = counterLogic(100, 10)
+
+        // ── 2. mouseTracker — lifecycle composable (needs setup context) ─────
+        const mouse = mouseTracker()
+
+        // ── 3. useLocalStorage — persists across page reloads ────────────────
+        const theme = useLocalStorage<string>('demo-theme', 'dark')
+        const nickname = useLocalStorage<string>('demo-nickname', '')
+
+        const toggleTheme = () => theme(theme() === 'dark' ? 'light' : 'dark')
+
+        // ── 4. useFetch — reactive data fetching ─────────────────────────────
+        const { data: posts, loading, error } = useFetch(
+            'https://jsonplaceholder.typicode.com/posts?_limit=3'
+        )
+        // ── 5. Custom Directives Test ────────────────────────────────────────
+        const hColor = signal('#8b8bff33')
+        const colors = ['#8b8bff33', '#10b98133', '#f59e0b33', '#ef444433']
+        let colorIdx = 0
+        const nextColor = () => hColor(colors[++colorIdx % colors.length])
+
+        return {
+            hColor,
+            nextColor,
+
+            // counter
+            count: counter.count,
+            doubled: counter.doubled,
+            isEven: counter.isEven,
+            increment: counter.increment,
+            decrement: counter.decrement,
+            reset: counter.reset,
+
+            // big counter
+            bigCount: bigCounter.count,
+            bigIncrement: bigCounter.increment,
+            bigDecrement: bigCounter.decrement,
+
+            // mouse
+            mouseX: mouse.x,
+            mouseY: mouse.y,
+
+            // localStorage
+            theme,
+            nickname,
+            toggleTheme,
+
+            // fetch
+            posts,
+            loading,
+            error,
+
+            template: `
+                <div class="page">
+                    <h1>🧩 Composables Demo</h1>
+                    <p style="color:#888; margin-bottom: 2rem;">
+                        Each section below is powered by a <code style="color:#ff3333">defineComposable()</code> function.
+                        No naming rules — just reactive logic.
+                    </p>
+
+                    <!-- ── 1. counterLogic ─────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>📦 counterLogic(0, step=1)</h2>
+                        <p class="demo-desc">Pure signal composable — works without setup() context.</p>
+                        <div class="counter-display">
+                            <span class="big-num" :class="isEven ? 'even' : 'odd'">{{ count }}</span>
+                            <span class="derived-label">× 2 = {{ doubled }}</span>
+                        </div>
+                        <div class="btn-row">
+                            <button @click="decrement" class="cmp-btn minus">−</button>
+                            <button @click="reset"     class="cmp-btn reset">↺</button>
+                            <button @click="increment" class="cmp-btn plus">+</button>
+                        </div>
+                        <p class="badge" :class="isEven ? 'badge-blue' : 'badge-red'">{{ isEven ? 'Even' : 'Odd' }}</p>
+                    </section>
+
+                    <!-- ── 1b. Second independent counter (step=10) ───────────── -->
+                    <section class="demo-card">
+                        <h2>📦 counterLogic(100, step=10)</h2>
+                        <p class="demo-desc">Same composable, different instance. Fully isolated state.</p>
+                        <div class="counter-display">
+                            <span class="big-num">{{ bigCount }}</span>
+                        </div>
+                        <div class="btn-row">
+                            <button @click="bigDecrement" class="cmp-btn minus">−10</button>
+                            <button @click="bigIncrement" class="cmp-btn plus">+10</button>
+                        </div>
+                    </section>
+
+                    <!-- ── 2. mouseTracker ────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>🖱️ mouseTracker()</h2>
+                        <p class="demo-desc">Lifecycle composable — registers window listener on mount, cleans up on unmount.</p>
+                        <div class="mouse-display">
+                            <span>X: <strong>{{ mouseX }}</strong></span>
+                            <span>Y: <strong>{{ mouseY }}</strong></span>
+                        </div>
+                    </section>
+
+                    <!-- ── 3. useLocalStorage ─────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>💾 useLocalStorage()</h2>
+                        <p class="demo-desc">State persists across page reloads. Try changing the nickname, then refresh.</p>
+                        <div style="margin-bottom: 12px;">
+                            <input f-model="nickname"
+                                   class="cmp-input"
+                                   placeholder="Your nickname…" />
+                            <p style="margin-top: 8px; color: #888; font-size: 0.85rem;">
+                                Stored: <strong style="color:#ff3333">{{ nickname || '(empty)' }}</strong>
+                            </p>
+                        </div>
+                        <button @click="toggleTheme" class="cmp-btn reset">
+                            Theme: {{ theme }}
+                        </button>
+                    </section>
+
+                    <!-- ── 4. useFetch ────────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>🌐 useFetch()</h2>
+                        <p class="demo-desc">Fetches from JSONPlaceholder. Loading state handled reactively.</p>
+                        <div f-if="loading">
+                            <p style="color: #888;">⏳ Loading posts…</p>
+                        </div>
+                        <div f-elif="error">
+                            <p style="color: #ff6b6b;">❌ {{ error }}</p>
+                        </div>
+                        <div f-else>
+                            <div f-for="post in posts" style="margin-bottom: 10px; padding: 10px; background:#1a1a24; border-radius:6px; border-left: 3px solid #ff3333;">
+                                <strong style="color:#ff9999">{{ post.title }}</strong>
+                                <p style="margin-top: 4px; font-size: 0.8rem; color: #666;">{{ post.body }}</p>
+                            </div>
+                        </div>
+                    </section>
+                    <!-- ── 6. Custom Directives ────────────────────────────────────── -->
+                    <section class="demo-card">
+                        <h2>🛠️ Custom Directives</h2>
+                        <p class="demo-desc">Testing <code>f-focus</code> and <code>f-highlight</code>.</p>
+                        
+                        <div f-highlight="hColor" style="padding: 15px; border-radius: 8px; margin-bottom: 10px;">
+                            <input f-focus class="cmp-input" placeholder="I have f-focus!" />
+                        </div>
+                        
+                        <button @click="nextColor" class="cmp-btn plus">Change Highlight Color</button>
+                    </section>
+                </div>
+            `
+        }
+    }
+})

package/app/routes/TestFor.js

@@ -11,11 +11,10 @@ export const TestFor = defineComponent({
             items,
             addItem: () => {
                 const nextId = Math.max(0, ...items().map(i => i.id)) + 1
-                items([...items(), { id: nextId, name: `Item ${nextId}` }])
+                items.push({ id: nextId, name: `Item ${nextId}` })
             },
             shuffleItems: () => {
-                const shuffled = [...items()].sort(() => Math.random() - 0.5)
-                items(shuffled)
+                items.sort(() => Math.random() - 0.5)
             },
             template: `
                 <div class="page">

package/app/routes/TestFor.ts

@@ -23,11 +23,10 @@ export const TestFor = defineComponent({
             addItem: () => {
                 const nextIds = items().map(i => i.id)
                 const nextId = nextIds.length > 0 ? Math.max(...nextIds) + 1 : 1
-                items([...items(), { id: nextId, name: `Item ${nextId}` }])
+                items.push({ id: nextId, name: `Item ${nextId}` })
             },
             shuffleItems: () => {
-                const shuffled = [...items()].sort(() => Math.random() - 0.5)
-                items(shuffled)
+                items.sort(() => Math.random() - 0.5)
             },
             template: `
                 <div class="page">

package/auto-imports.d.ts

@@ -9,6 +9,7 @@ declare global {
   const batch: typeof import('fusee-framework').batch
   const computed: typeof import('fusee-framework').computed
   const defineComponent: typeof import('fusee-framework').defineComponent
+  const directive: typeof import('fusee-framework').directive
   const effect: typeof import('fusee-framework').effect
   const emit: typeof import('fusee-framework').emit
   const inject: typeof import('fusee-framework').inject

package/framework/auto-import-preset.js

@@ -3,6 +3,7 @@ export const FuseePreset = {
         'signal', 'computed', 'effect',
         'batch', 'untrack', 'inspect',
         'defineComponent', 'onMount', 'onUnmount',
+        'directive',
         'mountOutlet', 'mountTemplate', 'emit'
     ]
 }

package/framework/core/component.js

@@ -7,6 +7,10 @@ setEffectHook(eff => {
     if (currentInstance) currentInstance._effects.push(eff)
 })
 
+export function getCurrentInstance() {
+    return currentInstance
+}
+
 function resolveProps(schema, received) {
     const isArray = Array.isArray(schema)
     const resolved = {}
@@ -68,9 +72,6 @@ function resolveProps(schema, received) {
     return resolved
 }
 
-// ── Emit ──────────────────────────────────────────────────────────────────────
-// listeners: { change: fn, submit: fn, ... }
-// emit('change', 42) → calls listeners.change(42)
 function createEmit(listeners) {
     return function emit(eventName, ...args) {
         const handler = listeners[eventName]
@@ -82,10 +83,6 @@ function createEmit(listeners) {
     }
 }
 
-// ── Slots ─────────────────────────────────────────────────────────────────────
-// Parses slot content from parent HTML string.
-// Named slots: <template slot="header">...</template>
-// Default slot: everything else
 export function parseSlots(slotHTML) {
     const slots = { default: '' }
     if (!slotHTML || !slotHTML.trim()) return slots
@@ -105,19 +102,15 @@ export function parseSlots(slotHTML) {
     return slots
 }
 
-// Replaces <slot> and <slot name="x"> in template with actual slot content
 function resolveSlots(template, slots) {
-    // Handle named slots with any content between tags (including default content)
     let result = template.replace(/<slot\s+name="([^"]+)"\s*>[\s\S]*?<\/slot>/gi, (match, name) => {
         return slots[name] ?? ''
     })
-    // Handle default slots with any content between tags
     result = result.replace(/<slot\s*>[\s\S]*?<\/slot>/gi, () => {
         return slots.default ?? ''
     })
-    // Handle self-closing named slots
+
     result = result.replace(/<slot\s+name="([^"]+)"\s*\/>/gi, (_, name) => slots[name] ?? '')
-    // Handle self-closing default slots
     result = result.replace(/<slot\s*\/>/gi, () => slots.default ?? '')
     return result
 }
@@ -131,10 +124,6 @@ export function onUnmount(fn) {
 }
 
 export function defineComponent(options) {
-    // ComponentFactory now accepts props + optional { listeners, slots, parent }
-    // listeners: event handlers from parent @eventName="handler"
-    // slots: parsed slot HTML from parent
-    // parent: parent component instance for provide/inject
     return function ComponentFactory(props = {}, { listeners = {}, slots = {}, parent = null } = {}) {
         const instance = {
             props: options.props ? resolveProps(options.props, props) : props,
@@ -149,16 +138,13 @@ export function defineComponent(options) {
         const emit = createEmit(listeners)
 
         currentInstance = instance
-        // setup() receives (props, { emit, slots })
         const result = options.setup(instance.props, { emit, slots })
-        // Store instance reference on result for child component access
         result._instance = instance
         currentInstance = null
 
         function render(container) {
             instance._element = container
 
-            // Resolve slot placeholders before mounting
             const resolvedTemplate = resolveSlots(result.template, slots)
 
             const { effects } = mountTemplate(
@@ -201,8 +187,8 @@ export function inject(key) {
 }
 
 export function defineAsyncComponent(loaderOrOptions) {
-    const options = typeof loaderOrOptions === 'function' 
-        ? { loader: loaderOrOptions } 
+    const options = typeof loaderOrOptions === 'function'
+        ? { loader: loaderOrOptions }
         : loaderOrOptions
 
     return function AsyncComponentFactory(props = {}, { listeners = {}, slots = {}, parent = null } = {}) {

package/framework/core/composable.js

@@ -0,0 +1,27 @@
+import { getCurrentInstance } from './component.js'
+
+export function defineComposable(fn) {
+    const composable = function (...args) {
+        return fn(...args)
+    }
+
+    composable._isComposable = true
+
+    Object.defineProperty(composable, 'name', {
+        value: fn.name || 'composable',
+        configurable: true
+    })
+
+    return composable
+}
+
+export function assertSetupContext(name) {
+    const instance = getCurrentInstance()
+    if (!instance) {
+        console.warn(
+            `[framework] ${name ? name + ' ' : ''}composable was called outside of setup(). ` +
+            `Lifecycle hooks (onMount, onUnmount) and injections will not work.`
+        )
+    }
+    return instance
+}

package/framework/core/directives.js

@@ -2,6 +2,73 @@ import { signal, effect, batch } from './signal.js'
 import { evaluateExpression } from './evaluator.js'
 import { compileNode } from './compiler.js'
 
+const customDirectives = new Map()
+
+export function directive(name, definition) {
+    if (typeof name !== 'string' || !name.trim()) {
+        console.error('[framework] directive() requires a non-empty name')
+        return
+    }
+    if (!definition || typeof definition !== 'object') {
+        console.error(`[framework] directive("${name}") requires a definition object`)
+        return
+    }
+    customDirectives.set(name, definition)
+}
+
+export function processCustomDirectives(el, context, effects) {
+    if (el.nodeType !== 1 || !el.hasAttribute || !el.attributes) return
+
+    for (const attr of [...el.attributes]) {
+        const match = attr.name.match(/^f-([a-zA-Z0-9-]+)(?::([a-zA-Z0-9-]+))?(?:\.(.+))?$/)
+
+        if (!match) continue
+
+        const directiveName = match[1]
+        const arg = match[2] || null
+        const modifiersStr = match[3]
+        const modifiers = modifiersStr ? modifiersStr.split('.') : []
+
+        const definition = customDirectives.get(directiveName)
+        if (!definition) {
+            continue
+        }
+
+        el.removeAttribute(attr.name)
+
+        const value = evaluateExpression(attr.value, context)
+        const expression = attr.value
+
+        const binding = {
+            value,
+            expression,
+            arg,
+            modifiers
+        }
+
+        if (typeof definition.mounted === 'function') {
+            definition.mounted(el, binding)
+        }
+
+        if (typeof definition.updated === 'function') {
+            effects.push(effect(() => {
+                const newValue = evaluateExpression(expression, context)
+
+                if (!Object.is(binding.value, newValue)) {
+                    binding.value = newValue
+                    definition.updated(el, binding)
+                }
+            }))
+        }
+
+        if (typeof definition.unmounted === 'function') {
+            effects.push(() => {
+                definition.unmounted(el, binding)
+            })
+        }
+    }
+}
+
 export function processDirectives(root, context, components, effects) {
     if (processFor(root, context, components, effects)) return true
     if (processIf(root, context, components, effects)) return true
@@ -13,6 +80,7 @@ export function processDirectives(root, context, components, effects) {
     processHtml(root, context, effects)
     processText(root, context, effects)
     processEvents(root, context, effects)
+    processCustomDirectives(root, context, effects)
     processCloak(root)
 
     return false
@@ -282,7 +350,7 @@ export function processIs(el, context, components, effects) {
     // 1. Prepare directive state
     const expr = el.getAttribute('f-is')
     const keepAlive = processKeepAlive(el)
-    
+
     el.removeAttribute('f-is')
 
     const anchor = document.createComment('f-keepAlive-anchor')

package/framework/core/signal.js

@@ -51,6 +51,64 @@ export function signal(initialValue) {
     }
 
     accessor.isSignal = true
+
+    if (Array.isArray(initialValue)) {
+        accessor.push = (...items) => {
+            const next = [...accessor(), ...items]
+            accessor(next)
+            return next.length
+        }
+
+        accessor.pop = () => {
+            const arr = accessor()
+            if (arr.length === 0) return undefined
+            const item = arr[arr.length - 1]
+            accessor(arr.slice(0, -1))
+            return item
+        }
+
+        accessor.shift = () => {
+            const arr = accessor()
+            if (arr.length === 0) return undefined
+            const item = arr[0]
+            accessor(arr.slice(1))
+            return item
+        }
+
+        accessor.unshift = (...items) => {
+            const next = [...items, ...accessor()]
+            accessor(next)
+            return next.length
+        }
+
+        accessor.splice = (start, deleteCount, ...items) => {
+            const arr = [...accessor()]
+            const removed = arr.splice(start, deleteCount, ...items)
+            accessor(arr)
+            return removed
+        }
+
+        accessor.remove = (predicate) => {
+            accessor(accessor().filter((item, i) => !predicate(item, i)))
+        }
+
+        accessor.clear = () => {
+            accessor([])
+        }
+
+        accessor.sort = (compareFn) => {
+            const next = [...accessor()].sort(compareFn)
+            accessor(next)
+            return accessor
+        }
+
+        accessor.reverse = () => {
+            const next = [...accessor()].reverse()
+            accessor(next)
+            return accessor
+        }
+    }
+
     return accessor
 }
 

package/framework/index.js

@@ -1,8 +1,10 @@
 // ─── Framework Public API ─────────────────────────────────────────────────────
 export { signal, computed, effect, batch, untrack, inspect } from './core/signal.js'
-export { defineComponent, defineAsyncComponent, onMount, onUnmount, parseSlots, provide, inject } from './core/component.js'
+export { defineComponent, defineAsyncComponent, onMount, onUnmount, parseSlots, provide, inject, getCurrentInstance } from './core/component.js'
 export { createRouter, navigate, mountOutlet } from './router/router.js'
 export { mountTemplate } from './core/compiler.js'
 
-// Emit is a placeholder - actual emit function is created per component
+export { defineComposable, assertSetupContext } from './core/composable.js'
+export { directive } from './core/directives.js'
+
 export const emit = () => console.warn('[framework] emit() can only be used inside component setup()')

package/framework/types/composable.d.ts

@@ -0,0 +1,14 @@
+export interface Composable<T = any> {
+    (...args: any[]): T
+    readonly _isComposable: true
+}
+
+declare global {
+    interface Composable<T = any> {
+        (...args: any[]): T
+        readonly _isComposable: true
+    }
+}
+
+export function defineComposable<T>(fn: (...args: any[]) => T): Composable<T>
+export function assertSetupContext(name?: string): any

package/framework/types/directives.d.ts

@@ -37,3 +37,18 @@ export function processHtml(root: HTMLElement, context: ComponentResult, effects
 export function processText(root: HTMLElement, context: ComponentResult, effects: (() => void)[]): void
 export function processEvents(root: HTMLElement, context: ComponentResult): void
 export function processCloak(root: HTMLElement): void
+
+export interface DirectiveBinding<V = any> {
+    value: V
+    expression: string
+    arg: string | null
+    modifiers: string[]
+}
+
+export interface DirectiveHooks<V = any> {
+    mounted?: (el: HTMLElement, binding: DirectiveBinding<V>) => void
+    updated?: (el: HTMLElement, binding: DirectiveBinding<V>) => void
+    unmounted?: (el: HTMLElement, binding: DirectiveBinding<V>) => void
+}
+
+export function directive<V = any>(name: string, hooks: DirectiveHooks<V>): void

package/framework/types/index.d.ts

@@ -1,16 +1,17 @@
-// ─── Fusée Framework Types ───────────────────────────────────────────────────
-
-// Public API
 export * from './signal'
 export * from './component'
+export * from './composable'
 export * from './router'
 export * from './compiler'
+export * from './directives'
 
 declare global {
     type Signal<T = any> = import('./signal').Signal<T>
     type Computed<T = any> = import('./signal').Computed<T>
     type SignalAccessor<T> = import('./signal').SignalAccessor<T>
+    type Composable<T extends (...args: any[]) => any> = import('./composable').Composable<T>
+    type DirectiveBinding<V = any> = import('./directives').DirectiveBinding<V>
+    type DirectiveHooks<V = any> = import('./directives').DirectiveHooks<V>
 }
 
-// Re-export as namespace for convenience
 export as namespace Fusee

package/framework/types/signal.d.ts

@@ -6,13 +6,25 @@ export type SignalAccessor<T> = {
     isSignal: boolean;
 }
 
+export type ArraySignalAccessor<T extends any[]> = SignalAccessor<T> & {
+    push(...items: T[number][]): number;
+    pop(): T[number] | undefined;
+    shift(): T[number] | undefined;
+    unshift(...items: T[number][]): number;
+    splice(start: number, deleteCount: number, ...items: T[number][]): T[number][];
+    remove(predicate: (item: T[number], index: number) => boolean): void;
+    clear(): void;
+    sort(compareFn?: (a: T[number], b: T[number]) => number): ArraySignalAccessor<T>;
+    reverse(): ArraySignalAccessor<T>;
+}
+
 export type ComputedAccessor<T> = {
     (): T;
     isSignal: boolean;
     readonly: true;
 }
 
-export type Signal<T = any> = SignalAccessor<T>
+export type Signal<T = any> = T extends any[] ? ArraySignalAccessor<T> : SignalAccessor<T>
 export type Computed<T = any> = ComputedAccessor<T>
 
 type EffectRunner = {
@@ -20,7 +32,8 @@ type EffectRunner = {
     deps: Set<Set<EffectRunner>>;
 }
 
-export declare function signal<T>(initialValue: T): Signal<T>
+export declare function signal<T extends any[]>(initialValue: T): ArraySignalAccessor<T>
+export declare function signal<T>(initialValue: T): SignalAccessor<T>
 export declare function effect(fn: () => void): () => void
 export declare function computed<T>(fn: () => T): Computed<T>
 export declare function batch<T>(fn: () => T): T

package/index.html

@@ -160,6 +160,139 @@
       opacity: 0.3;
       cursor: not-allowed;
     }
+
+    /* ── Composables demo ──────────────────────────────────────────── */
+    .demo-card {
+      background: #13131d;
+      border: 1px solid #2a2a3a;
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .demo-card h2 {
+      font-size: 1rem;
+      font-weight: 600;
+      color: #e8e8f0;
+      margin-bottom: 0.35rem;
+    }
+
+    .demo-desc {
+      font-size: 0.8rem;
+      color: #555 !important;
+      margin-bottom: 1rem !important;
+    }
+
+    .counter-display {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      margin-bottom: 1rem;
+    }
+
+    .big-num {
+      font-size: 3.5rem;
+      font-weight: 700;
+      line-height: 1;
+      transition: color 0.2s;
+    }
+
+    .big-num.even {
+      color: #8b8bff;
+    }
+
+    .big-num.odd {
+      color: #ff3333;
+    }
+
+    .derived-label {
+      font-size: 0.8rem;
+      color: #555;
+      margin-top: 0.25rem;
+    }
+
+    .btn-row {
+      display: flex;
+      gap: 0.5rem;
+      justify-content: center;
+      margin-bottom: 0.75rem;
+    }
+
+    .cmp-btn {
+      padding: 0.45rem 1.1rem;
+      border-radius: 6px;
+      border: 1px solid #2a2a3a;
+      background: #0f0f1a;
+      color: #e8e8f0;
+      cursor: pointer;
+      font-size: 1rem;
+      transition: background 0.15s;
+    }
+
+    .cmp-btn:hover {
+      background: #1f1f30;
+    }
+
+    .cmp-btn.plus {
+      border-color: #8b8bff;
+      color: #8b8bff;
+    }
+
+    .cmp-btn.minus {
+      border-color: #ff3333;
+      color: #ff3333;
+    }
+
+    .cmp-btn.reset {
+      border-color: #555;
+      color: #888;
+    }
+
+    .badge {
+      display: inline-block;
+      padding: 0.2rem 0.65rem;
+      border-radius: 999px;
+      font-size: 0.75rem;
+      font-weight: 600;
+    }
+
+    .badge-blue {
+      background: rgba(139, 139, 255, 0.15);
+      color: #8b8bff;
+    }
+
+    .badge-red {
+      background: rgba(255, 51, 51, 0.12);
+      color: #ff3333;
+    }
+
+    .mouse-display {
+      display: flex;
+      gap: 2rem;
+      font-size: 1.1rem;
+      color: #aaa;
+      margin-bottom: 0.5rem;
+    }
+
+    .mouse-display strong {
+      color: #e8e8f0;
+    }
+
+    .cmp-input {
+      width: 100%;
+      padding: 0.5rem 0.75rem;
+      background: #0f0f1a;
+      border: 1px solid #2a2a3a;
+      border-radius: 6px;
+      color: #e8e8f0;
+      font-size: 0.95rem;
+      outline: none;
+      transition: border-color 0.15s;
+    }
+
+    .cmp-input:focus {
+      border-color: #8b8bff;
+    }
   </style>
 </head>
 
@@ -169,9 +302,10 @@
     <a href="#/about">About</a>
     <a href="#/test-for">Loops Test</a>
     <a href="#/dynamic" style="color: #ec4899;">Dynamic Components</a>
+    <a href="#/composables" style="color: #34d399;">Composables</a>
   </nav>
   <div id="app"></div>
-  <script type="module" src="./app/main.js"></script>
+  <script type="module" src="./app/main.ts"></script>
 </body>
 
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fusee-framework",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Fusée - Signals-first JS Framework | Peak Performance",
   "main": "framework/index.js",
   "types": "framework/types/index.d.ts",