gonia 0.1.3 → 0.2.0

package/README.md

@@ -58,18 +58,16 @@ hydrate();
 ```typescript
 import { directive, Directive } from 'gonia';
 
-const myApp: Directive = ($element, $state) => {
-  // Initialize state
-  $state.count = 0;
+const myApp: Directive<['$element', '$scope']> = ($element, $scope) => {
+  // Initialize scope
+  $scope.count = 0;
 
   // Define methods
-  $state.increment = () => {
-    $state.count++;
+  $scope.increment = () => {
+    $scope.count++;
   };
 };
 
-myApp.$inject = ['$element', '$state'];
-
 // Register with scope: true to create isolated state
 directive('my-app', myApp, { scope: true });
 ```
@@ -92,6 +90,8 @@ directive('my-app', myApp, { scope: true });
 | `g-class` | Dynamic classes | `<div g-class="{ active: isActive }">` |
 | `g-model` | Two-way binding | `<input g-model="name">` |
 | `g-on` | Event handling | `<button g-on="click: handleClick">` |
+| `g-scope` | Inline scope init | `<div g-scope="{ count: 0 }">` |
+| `g-bind:*` | Dynamic attributes | `<a g-bind:href="link">` |
 
 ## Vite Integration
 
@@ -114,6 +114,23 @@ See the [docs](./docs) folder for detailed documentation:
 - [SSR Guide](./docs/ssr.md)
 - [Reactivity](./docs/reactivity.md)
 
+## Roadmap
+
+### Done
+- [x] Core directives (`g-text`, `g-show`, `g-if`, `g-for`, `g-class`, `g-model`, `g-on`, `g-scope`, `g-bind:*`, `g-html`)
+- [x] Directive options (`scope`, `template`, `assign`, `provide`, `using`)
+- [x] SSR with client hydration
+- [x] Vite plugin with `$inject` transformation
+- [x] Typed context registry
+- [x] Persistent scopes for `g-if` toggles
+
+### Planned
+- [ ] Reducer-based two-way bindings (`scope: { prop: '=' }`)
+- [ ] Scoped CSS with automatic class mangling
+- [ ] Async components with suspense boundaries
+- [ ] Browser devtools extension
+- [ ] Transition system for `g-if`/`g-for`
+
 ## License
 
 MIT

package/dist/client/hydrate.js

@@ -11,6 +11,7 @@ import { FOR_PROCESSED_ATTR } from '../directives/for.js';
 import { findParentScope, createElementScope, getElementScope } from '../scope.js';
 import { resolveDependencies as resolveInjectables } from '../inject.js';
 import { resolveContext } from '../context-registry.js';
+import { effect } from '../reactivity.js';
 // Built-in directives
 import { text } from '../directives/text.js';
 import { show } from '../directives/show.js';
@@ -60,6 +61,10 @@ function getSelector(registry) {
         }
         // Also match native <slot> elements
         directiveSelectors.push('slot');
+        // Match template placeholders from SSR (g-if with false condition)
+        directiveSelectors.push('template[data-g-if]');
+        // Match g-scope for inline scope initialization
+        directiveSelectors.push('[g-scope]');
         cachedSelector = directiveSelectors.join(',');
     }
     return cachedSelector;
@@ -172,10 +177,54 @@ function processElement(el, registry) {
         processNativeSlot(el);
         return;
     }
+    // Handle template placeholders from SSR (g-if with false condition)
+    if (el.tagName === 'TEMPLATE' && el.hasAttribute('data-g-if')) {
+        const ifDirective = registry.get('if');
+        if (ifDirective) {
+            const expr = el.getAttribute('data-g-if') || '';
+            const ctx = getContextForElement(el);
+            const config = createClientResolverConfig(el, ctx);
+            const registration = getDirective('g-if');
+            const args = resolveInjectables(ifDirective, expr, el, ctx.eval.bind(ctx), config, registration?.options.using);
+            const result = ifDirective(...args);
+            if (result instanceof Promise) {
+                return result;
+            }
+        }
+        return;
+    }
     const directives = getDirectivesForElement(el, registry);
-    if (directives.length === 0)
+    const hasScopeAttr = el.hasAttribute('g-scope');
+    const hasBindAttrs = [...el.attributes].some(a => a.name.startsWith('g-bind:'));
+    // Skip if nothing to process
+    if (directives.length === 0 && !hasScopeAttr && !hasBindAttrs)
         return;
     const ctx = getContextForElement(el);
+    const scope = findParentScope(el, true) ?? {};
+    // Process g-scope first (inline scope initialization)
+    if (hasScopeAttr) {
+        const scopeAttr = el.getAttribute('g-scope');
+        const scopeValues = ctx.eval(scopeAttr);
+        if (scopeValues && typeof scopeValues === 'object') {
+            Object.assign(scope, scopeValues);
+        }
+    }
+    // Process g-bind:* attributes (dynamic attribute binding with reactivity)
+    for (const attr of [...el.attributes]) {
+        if (attr.name.startsWith('g-bind:')) {
+            const targetAttr = attr.name.slice('g-bind:'.length);
+            const valueExpr = attr.value;
+            effect(() => {
+                const value = ctx.eval(valueExpr);
+                if (value === null || value === undefined) {
+                    el.removeAttribute(targetAttr);
+                }
+                else {
+                    el.setAttribute(targetAttr, String(value));
+                }
+            });
+        }
+    }
     // Process directives sequentially, handling async ones properly
     let chain;
     for (const { directive, expr, using } of directives) {
@@ -335,6 +384,10 @@ async function processDirectiveElements() {
             if (options.scope) {
                 const parentScope = findParentScope(el);
                 scope = createElementScope(el, parentScope);
+                // Apply assigned values to scope
+                if (options.assign) {
+                    Object.assign(scope, options.assign);
+                }
             }
             else {
                 scope = findParentScope(el, true) ?? {};

package/dist/directives/for.d.ts

@@ -26,4 +26,4 @@ export declare const FOR_TEMPLATE_ATTR = "data-g-for-template";
  * <div g-for="(value, key) in object" g-text="key + ': ' + value"></div>
  * ```
  */
-export declare const cfor: Directive<['$expr', '$element', '$eval', '$state', '$mode']>;
+export declare const cfor: Directive<['$expr', '$element', '$eval', '$scope', '$mode']>;

package/dist/directives/for.js

@@ -4,8 +4,8 @@
  * @packageDocumentation
  */
 import { directive, DirectivePriority, Mode } from '../types.js';
-import { effect, createEffectScope, createScope } from '../reactivity.js';
-import { createContext } from '../context.js';
+import { effect, createEffectScope } from '../reactivity.js';
+import { processElementTree } from '../process.js';
 /**
  * Parse a g-for expression.
  *
@@ -31,77 +31,10 @@ function parseForExpression(expr) {
 export const FOR_PROCESSED_ATTR = 'data-g-for-processed';
 /** Attribute used to mark template content that should be skipped during SSR */
 export const FOR_TEMPLATE_ATTR = 'data-g-for-template';
-/**
- * Process directives on a cloned element within a child scope.
- */
-function processClonedElement(el, parentState, scopeAdditions, mode) {
-    // Mark this element as processed by g-for so hydrate skips it
-    el.setAttribute(FOR_PROCESSED_ATTR, '');
-    const childScope = createScope(parentState, scopeAdditions);
-    const childCtx = createContext(mode, childScope);
-    // Process g-text directives
-    const textAttr = el.getAttribute('g-text');
-    if (textAttr) {
-        const value = childCtx.eval(textAttr);
-        el.textContent = String(value ?? '');
-    }
-    // Process g-class directives
-    const classAttr = el.getAttribute('g-class');
-    if (classAttr) {
-        const classObj = childCtx.eval(classAttr);
-        if (classObj && typeof classObj === 'object') {
-            for (const [className, shouldAdd] of Object.entries(classObj)) {
-                if (shouldAdd) {
-                    el.classList.add(className);
-                }
-                else {
-                    el.classList.remove(className);
-                }
-            }
-        }
-    }
-    // Process g-show directives
-    const showAttr = el.getAttribute('g-show');
-    if (showAttr) {
-        const value = childCtx.eval(showAttr);
-        el.style.display = value ? '' : 'none';
-    }
-    // Process g-on directives (format: "event: handler") - client only
-    if (mode === Mode.CLIENT) {
-        const onAttr = el.getAttribute('g-on');
-        if (onAttr) {
-            setupEventHandler(el, onAttr, childCtx, childScope);
-        }
-    }
-    // Process children recursively
-    for (const child of el.children) {
-        processClonedElement(child, childScope, {}, mode);
-    }
-}
-/**
- * Set up an event handler on an element.
- * Expression format: "event: handler"
- */
-function setupEventHandler(el, expr, ctx, state) {
-    const colonIdx = expr.indexOf(':');
-    if (colonIdx === -1) {
-        console.error(`Invalid g-on expression: ${expr}. Expected "event: handler"`);
-        return;
-    }
-    const eventName = expr.slice(0, colonIdx).trim();
-    const handlerExpr = expr.slice(colonIdx + 1).trim();
-    const handler = (event) => {
-        const result = ctx.eval(handlerExpr);
-        if (typeof result === 'function') {
-            result.call(state, event);
-        }
-    };
-    el.addEventListener(eventName, handler);
-}
 /**
  * Render loop items (used by both server and client).
  */
-function renderItems(template, parent, insertAfterNode, parsed, $eval, $state, mode) {
+function renderItems(template, parent, insertAfterNode, parsed, $eval, $scope, mode) {
     const { itemName, indexName, iterableName } = parsed;
     const iterable = $eval(iterableName);
     const renderedElements = [];
@@ -136,7 +69,10 @@ function renderItems(template, parent, insertAfterNode, parsed, $eval, $state, m
         if (indexName) {
             scopeAdditions[indexName] = key;
         }
-        processClonedElement(clone, $state, scopeAdditions, mode);
+        // Mark as processed
+        clone.setAttribute(FOR_PROCESSED_ATTR, '');
+        // Process with shared utility
+        processElementTree(clone, $scope, mode, { scopeAdditions });
         if (insertAfter.nextSibling) {
             parent.insertBefore(clone, insertAfter.nextSibling);
         }
@@ -177,7 +113,7 @@ function removeSSRItems(templateEl) {
  * <div g-for="(value, key) in object" g-text="key + ': ' + value"></div>
  * ```
  */
-export const cfor = function cfor($expr, $element, $eval, $state, $mode) {
+export const cfor = function cfor($expr, $element, $eval, $scope, $mode) {
     const parsed = parseForExpression($expr);
     if (!parsed) {
         console.error(`Invalid g-for expression: ${$expr}`);
@@ -204,7 +140,7 @@ export const cfor = function cfor($expr, $element, $eval, $state, $mode) {
         // Replace original with template wrapper
         parent.replaceChild(templateWrapper, $element);
         // Render items after the template
-        renderItems(templateContent, parent, templateWrapper, parsed, $eval, $state, $mode);
+        renderItems(templateContent, parent, templateWrapper, parsed, $eval, $scope, $mode);
         return;
     }
     // Client-side: check if hydrating from SSR or fresh render
@@ -230,7 +166,7 @@ export const cfor = function cfor($expr, $element, $eval, $state, $mode) {
             }
             scope = createEffectScope();
             scope.run(() => {
-                renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $state, Mode.CLIENT);
+                renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $scope, Mode.CLIENT);
             });
         });
     }
@@ -255,11 +191,11 @@ export const cfor = function cfor($expr, $element, $eval, $state, $mode) {
             }
             scope = createEffectScope();
             scope.run(() => {
-                renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $state, Mode.CLIENT);
+                renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $scope, Mode.CLIENT);
             });
         });
     }
 };
-cfor.$inject = ['$expr', '$element', '$eval', '$state', '$mode'];
+cfor.$inject = ['$expr', '$element', '$eval', '$scope', '$mode'];
 cfor.priority = DirectivePriority.STRUCTURAL;
 directive('g-for', cfor);

package/dist/directives/if.d.ts

@@ -13,6 +13,9 @@ export declare const IF_PROCESSED_ATTR = "data-g-if-processed";
  * Unlike g-show which uses display:none, g-if completely removes
  * the element from the DOM when the condition is falsy.
  *
+ * State within the conditional block is preserved across toggles.
+ * The scope is anchored to the placeholder, not the rendered element.
+ *
  * On server: evaluates once and removes element if false.
  * On client: sets up reactive effect to toggle element.
  *
@@ -22,4 +25,4 @@ export declare const IF_PROCESSED_ATTR = "data-g-if-processed";
  * <div g-if="items.length > 0">Has items</div>
  * ```
  */
-export declare const cif: Directive<['$expr', '$element', '$eval', '$state', '$mode']>;
+export declare const cif: Directive<['$expr', '$element', '$eval', '$scope', '$mode']>;

package/dist/directives/if.js

@@ -4,66 +4,30 @@
  * @packageDocumentation
  */
 import { directive, DirectivePriority, Mode } from '../types.js';
-import { effect } from '../reactivity.js';
-import { createContext } from '../context.js';
-import { createScope } from '../reactivity.js';
+import { effect, createScope } from '../reactivity.js';
+import { processElementTree } from '../process.js';
 /** Attribute used to mark elements processed by g-if */
 export const IF_PROCESSED_ATTR = 'data-g-if-processed';
+/** WeakMap to store persistent scopes for g-if placeholders */
+const placeholderScopes = new WeakMap();
 /**
- * Process directives on a conditionally rendered element.
+ * Get or create a persistent scope for a g-if placeholder.
+ *
+ * @remarks
+ * The scope is anchored to the placeholder element, not the rendered content.
+ * This allows state to persist across condition toggles.
+ *
+ * @param placeholder - The template placeholder element
+ * @param parentState - The parent scope to inherit from
+ * @returns The persistent scope for this g-if block
  */
-function processConditionalElement(el, parentState, mode) {
-    el.setAttribute(IF_PROCESSED_ATTR, '');
-    const childScope = createScope(parentState, {});
-    const childCtx = createContext(mode, childScope);
-    // Process g-text directives
-    const textAttr = el.getAttribute('g-text');
-    if (textAttr) {
-        const value = childCtx.eval(textAttr);
-        el.textContent = String(value ?? '');
-    }
-    // Process g-class directives
-    const classAttr = el.getAttribute('g-class');
-    if (classAttr) {
-        const classObj = childCtx.eval(classAttr);
-        if (classObj && typeof classObj === 'object') {
-            for (const [className, shouldAdd] of Object.entries(classObj)) {
-                if (shouldAdd) {
-                    el.classList.add(className);
-                }
-                else {
-                    el.classList.remove(className);
-                }
-            }
-        }
-    }
-    // Process g-show directives
-    const showAttr = el.getAttribute('g-show');
-    if (showAttr) {
-        const value = childCtx.eval(showAttr);
-        el.style.display = value ? '' : 'none';
-    }
-    // Process g-on directives (format: "event: handler") - client only
-    if (mode === Mode.CLIENT) {
-        const onAttr = el.getAttribute('g-on');
-        if (onAttr) {
-            const colonIdx = onAttr.indexOf(':');
-            if (colonIdx !== -1) {
-                const eventName = onAttr.slice(0, colonIdx).trim();
-                const handlerExpr = onAttr.slice(colonIdx + 1).trim();
-                el.addEventListener(eventName, (event) => {
-                    const result = childCtx.eval(handlerExpr);
-                    if (typeof result === 'function') {
-                        result.call(childScope, event);
-                    }
-                });
-            }
-        }
-    }
-    // Process children recursively
-    for (const child of el.children) {
-        processConditionalElement(child, childScope, mode);
+function getOrCreateScope(placeholder, parentState) {
+    let scope = placeholderScopes.get(placeholder);
+    if (!scope) {
+        scope = createScope(parentState, {});
+        placeholderScopes.set(placeholder, scope);
     }
+    return scope;
 }
 /**
  * Conditionally render an element.
@@ -72,6 +36,9 @@ function processConditionalElement(el, parentState, mode) {
  * Unlike g-show which uses display:none, g-if completely removes
  * the element from the DOM when the condition is falsy.
  *
+ * State within the conditional block is preserved across toggles.
+ * The scope is anchored to the placeholder, not the rendered element.
+ *
  * On server: evaluates once and removes element if false.
  * On client: sets up reactive effect to toggle element.
  *
@@ -81,37 +48,72 @@ function processConditionalElement(el, parentState, mode) {
  * <div g-if="items.length > 0">Has items</div>
  * ```
  */
-export const cif = function cif($expr, $element, $eval, $state, $mode) {
+export const cif = function cif($expr, $element, $eval, $scope, $mode) {
     const parent = $element.parentNode;
     if (!parent) {
         return;
     }
-    // Server-side: evaluate once and remove if false
+    // Server-side: evaluate once and leave template placeholder if false
     if ($mode === Mode.SERVER) {
         const condition = $eval($expr);
         if (!condition) {
+            // Leave a template marker so client hydration knows where to insert
+            const placeholder = $element.ownerDocument.createElement('template');
+            placeholder.setAttribute('data-g-if', String($expr));
+            // Store original element inside template for hydration
+            placeholder.innerHTML = $element.outerHTML;
+            parent.insertBefore(placeholder, $element);
             $element.remove();
         }
         else {
             // Process child directives
             $element.removeAttribute('g-if');
-            processConditionalElement($element, $state, $mode);
+            $element.setAttribute(IF_PROCESSED_ATTR, '');
+            processElementTree($element, $scope, $mode);
         }
         return;
     }
-    // Client-side: set up reactive effect
-    const placeholder = $element.ownerDocument.createComment(` g-if: ${$expr} `);
-    parent.insertBefore(placeholder, $element);
-    const template = $element.cloneNode(true);
-    template.removeAttribute('g-if');
-    $element.remove();
+    // Client-side: check if this is a template placeholder (from SSR)
+    const isTemplatePlaceholder = $element.tagName === 'TEMPLATE' && $element.hasAttribute('data-g-if');
+    let placeholder;
+    let template;
+    if (isTemplatePlaceholder) {
+        // Hydrating SSR output - template is the placeholder, content is inside
+        placeholder = $element;
+        const content = $element.content.firstElementChild
+            || $element.innerHTML;
+        if (typeof content === 'string') {
+            const temp = $element.ownerDocument.createElement('div');
+            temp.innerHTML = content;
+            template = temp.firstElementChild;
+        }
+        else {
+            template = content.cloneNode(true);
+        }
+        template.removeAttribute('g-if');
+    }
+    else {
+        // Pure client-side - create template placeholder
+        placeholder = $element.ownerDocument.createElement('template');
+        placeholder.setAttribute('data-g-if', String($expr));
+        parent.insertBefore(placeholder, $element);
+        template = $element.cloneNode(true);
+        template.removeAttribute('g-if');
+        $element.remove();
+    }
+    // Create persistent scope anchored to the placeholder
+    const persistentScope = getOrCreateScope(placeholder, $scope);
     let renderedElement = null;
     effect(() => {
         const condition = $eval($expr);
         if (condition) {
             if (!renderedElement) {
                 renderedElement = template.cloneNode(true);
-                processConditionalElement(renderedElement, $state, Mode.CLIENT);
+                renderedElement.setAttribute(IF_PROCESSED_ATTR, '');
+                // Process with the persistent scope - state survives across toggles
+                processElementTree(renderedElement, $scope, Mode.CLIENT, {
+                    existingScope: persistentScope
+                });
                 if (placeholder.nextSibling) {
                     parent.insertBefore(renderedElement, placeholder.nextSibling);
                 }
@@ -124,10 +126,11 @@ export const cif = function cif($expr, $element, $eval, $state, $mode) {
             if (renderedElement) {
                 renderedElement.remove();
                 renderedElement = null;
+                // Scope survives in persistentScope - ready for next render
             }
         }
     });
 };
-cif.$inject = ['$expr', '$element', '$eval', '$state', '$mode'];
+cif.$inject = ['$expr', '$element', '$eval', '$scope', '$mode'];
 cif.priority = DirectivePriority.STRUCTURAL;
 directive('g-if', cif);

package/dist/expression.js

@@ -43,8 +43,23 @@ export function findRoots(expr) {
         .replace(/'(?:[^'\\]|\\.)*'/g, '""')
         .replace(/"(?:[^"\\]|\\.)*"/g, '""')
         .replace(/`(?:[^`\\$]|\\.|\$(?!\{))*`/g, '""');
-    const matches = cleaned.match(/(?<![.\w$])\b[a-zA-Z_$][a-zA-Z0-9_$]*\b/g) || [];
-    const roots = [...new Set(matches.filter(m => !JS_KEYWORDS.has(m)))];
+    // Match identifiers that are not preceded by a dot
+    // Use simpler approach: match all identifiers, then filter out property accesses
+    const allIdentifiers = cleaned.match(/[a-zA-Z_$][a-zA-Z0-9_$]*/g) || [];
+    // Filter to keep only root identifiers (not after a dot)
+    const roots = [];
+    let lastEnd = 0;
+    for (const id of allIdentifiers) {
+        const pos = cleaned.indexOf(id, lastEnd);
+        // Check if preceded by a dot (with optional whitespace)
+        const before = cleaned.slice(0, pos).trimEnd();
+        if (!before.endsWith('.')) {
+            if (!JS_KEYWORDS.has(id) && !roots.includes(id)) {
+                roots.push(id);
+            }
+        }
+        lastEnd = pos + id.length;
+    }
     return roots;
 }
 /**

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { getInjectables, isContextKey } from './inject.js';
 export type { Injectable } from './inject.js';
 export { getRootScope, clearRootScope } from './scope.js';
 export { findAncestor } from './dom.js';
+export { processElementDirectives, processElementTree, PROCESSED_ATTR } from './process.js';
+export type { ProcessOptions } from './process.js';
 export { createContextKey, registerContext, resolveContext, hasContext, removeContext, clearContexts } from './context-registry.js';
 export type { ContextKey } from './context-registry.js';
 export * as directives from './directives/index.js';

package/dist/index.js

@@ -15,5 +15,6 @@ export { findRoots, parseInterpolation } from './expression.js';
 export { getInjectables, isContextKey } from './inject.js';
 export { getRootScope, clearRootScope } from './scope.js';
 export { findAncestor } from './dom.js';
+export { processElementDirectives, processElementTree, PROCESSED_ATTR } from './process.js';
 export { createContextKey, registerContext, resolveContext, hasContext, removeContext, clearContexts } from './context-registry.js';
 export * as directives from './directives/index.js';

package/dist/inject.d.ts

@@ -55,7 +55,7 @@ export declare function getInjectables(fn: InjectableFunction): Injectable[];
 export interface DependencyResolverConfig {
     /** Resolve a ContextKey to its value */
     resolveContext: (key: ContextKey<unknown>) => unknown;
-    /** Resolve $state injectable */
+    /** Resolve $scope injectable */
     resolveState: () => Record<string, unknown>;
     /** Resolve $rootState injectable (may be same as state) */
     resolveRootState?: () => Record<string, unknown>;

package/dist/inject.js

@@ -97,7 +97,7 @@ export function resolveDependencies(fn, expr, element, evalFn, config, using) {
                 return element;
             case '$eval':
                 return evalFn;
-            case '$state':
+            case '$scope':
                 return config.resolveState();
             case '$rootState':
                 return config.resolveRootState?.() ?? config.resolveState();

package/dist/process.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared element processing for structural directives.
+ *
+ * @remarks
+ * Provides a unified way to process directives on elements created by
+ * structural directives like g-if and g-for. Supports scope reuse for
+ * state preservation across re-renders.
+ *
+ * @packageDocumentation
+ */
+import { Mode } from './types.js';
+/** Attribute used to mark elements processed by structural directives */
+export declare const PROCESSED_ATTR = "data-g-processed";
+/**
+ * Options for processing element directives.
+ */
+export interface ProcessOptions {
+    /**
+     * Existing scope to use instead of creating a new one.
+     * Use this to preserve state across re-renders (e.g., g-if toggle).
+     */
+    existingScope?: Record<string, unknown>;
+    /**
+     * Additional properties to add to the scope.
+     * Used by g-for to add item/index variables.
+     */
+    scopeAdditions?: Record<string, unknown>;
+    /**
+     * Skip processing structural directives (g-for, g-if).
+     * Set to true when processing content inside a structural directive
+     * to avoid infinite recursion.
+     */
+    skipStructural?: boolean;
+}
+/**
+ * Process directives on an element using registered directives.
+ *
+ * @remarks
+ * This processes all non-structural directives (g-text, g-class, g-show, g-on, etc.)
+ * on an element. For structural directives, use the directives directly.
+ *
+ * @param el - The element to process
+ * @param parentScope - The parent scope for variable resolution
+ * @param mode - Server or client mode
+ * @param options - Processing options
+ * @returns The scope used for this element (for chaining/children)
+ */
+export declare function processElementDirectives(el: Element, parentScope: Record<string, unknown>, mode: Mode, options?: ProcessOptions): Record<string, unknown>;
+/**
+ * Process an element tree (element and all descendants).
+ *
+ * @remarks
+ * Recursively processes directives on an element and all its children.
+ * Each child gets its own scope that inherits from the parent.
+ *
+ * @param el - The root element to process
+ * @param parentScope - The parent scope
+ * @param mode - Server or client mode
+ * @param options - Processing options (existingScope only applies to root element)
+ */
+export declare function processElementTree(el: Element, parentScope: Record<string, unknown>, mode: Mode, options?: ProcessOptions): void;

package/dist/process.js

@@ -0,0 +1,215 @@
+/**
+ * Shared element processing for structural directives.
+ *
+ * @remarks
+ * Provides a unified way to process directives on elements created by
+ * structural directives like g-if and g-for. Supports scope reuse for
+ * state preservation across re-renders.
+ *
+ * @packageDocumentation
+ */
+import { Mode, getDirective } from './types.js';
+import { createContext } from './context.js';
+import { createScope, effect } from './reactivity.js';
+import { resolveDependencies } from './inject.js';
+import { resolveContext } from './context-registry.js';
+import { resolveFromProviders, resolveFromDIProviders } from './providers.js';
+/** Attribute used to mark elements processed by structural directives */
+export const PROCESSED_ATTR = 'data-g-processed';
+/**
+ * Create resolver config for dependency resolution.
+ *
+ * @internal
+ */
+function createResolverConfig(el, scope, mode) {
+    return {
+        resolveContext: (key) => resolveContext(el, key),
+        resolveState: () => scope,
+        resolveRootState: () => scope,
+        resolveCustom: (name) => {
+            const diProvided = resolveFromDIProviders(el, name);
+            if (diProvided !== undefined)
+                return diProvided;
+            return resolveFromProviders(el, name);
+        },
+        mode: mode === Mode.SERVER ? 'server' : 'client'
+    };
+}
+/**
+ * Set up an event handler on an element.
+ *
+ * @internal
+ */
+function setupEventHandler(el, expr, ctx, scope) {
+    const colonIdx = expr.indexOf(':');
+    if (colonIdx === -1) {
+        return;
+    }
+    const eventName = expr.slice(0, colonIdx).trim();
+    const handlerExpr = expr.slice(colonIdx + 1).trim();
+    el.addEventListener(eventName, (event) => {
+        const result = ctx.eval(handlerExpr);
+        if (typeof result === 'function') {
+            result.call(scope, event);
+        }
+    });
+}
+/**
+ * Process directives on an element using registered directives.
+ *
+ * @remarks
+ * This processes all non-structural directives (g-text, g-class, g-show, g-on, etc.)
+ * on an element. For structural directives, use the directives directly.
+ *
+ * @param el - The element to process
+ * @param parentScope - The parent scope for variable resolution
+ * @param mode - Server or client mode
+ * @param options - Processing options
+ * @returns The scope used for this element (for chaining/children)
+ */
+export function processElementDirectives(el, parentScope, mode, options = {}) {
+    const { existingScope, scopeAdditions = {}, skipStructural = true } = options;
+    // Mark element as processed
+    el.setAttribute(PROCESSED_ATTR, '');
+    // Use existing scope or create a new child scope
+    const scope = existingScope
+        ? (Object.keys(scopeAdditions).length > 0
+            ? createScope(existingScope, scopeAdditions)
+            : existingScope)
+        : createScope(parentScope, scopeAdditions);
+    const ctx = createContext(mode, scope);
+    // Process g-scope (inline scope initialization)
+    const scopeAttr = el.getAttribute('g-scope');
+    if (scopeAttr) {
+        const scopeValues = ctx.eval(scopeAttr);
+        if (scopeValues && typeof scopeValues === 'object') {
+            Object.assign(scope, scopeValues);
+        }
+    }
+    // Process g-text
+    const textAttr = el.getAttribute('g-text');
+    if (textAttr) {
+        if (mode === Mode.CLIENT) {
+            effect(() => {
+                const value = ctx.eval(textAttr);
+                el.textContent = String(value ?? '');
+            });
+        }
+        else {
+            const value = ctx.eval(textAttr);
+            el.textContent = String(value ?? '');
+        }
+    }
+    // Process g-class
+    const classAttr = el.getAttribute('g-class');
+    if (classAttr) {
+        const applyClasses = () => {
+            const classObj = ctx.eval(classAttr);
+            if (classObj && typeof classObj === 'object') {
+                for (const [className, shouldAdd] of Object.entries(classObj)) {
+                    if (shouldAdd) {
+                        el.classList.add(className);
+                    }
+                    else {
+                        el.classList.remove(className);
+                    }
+                }
+            }
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyClasses);
+        }
+        else {
+            applyClasses();
+        }
+    }
+    // Process g-show
+    const showAttr = el.getAttribute('g-show');
+    if (showAttr) {
+        const applyShow = () => {
+            const value = ctx.eval(showAttr);
+            el.style.display = value ? '' : 'none';
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyShow);
+        }
+        else {
+            applyShow();
+        }
+    }
+    // Process g-on (client only)
+    if (mode === Mode.CLIENT) {
+        const onAttr = el.getAttribute('g-on');
+        if (onAttr) {
+            setupEventHandler(el, onAttr, ctx, scope);
+        }
+    }
+    // Process g-model (client only)
+    if (mode === Mode.CLIENT) {
+        const modelAttr = el.getAttribute('g-model');
+        if (modelAttr) {
+            const registration = getDirective('g-model');
+            if (registration?.fn) {
+                const config = createResolverConfig(el, scope, mode);
+                const args = resolveDependencies(registration.fn, modelAttr, el, ctx.eval.bind(ctx), config, registration.options.using);
+                registration.fn(...args);
+            }
+        }
+    }
+    // Process g-html
+    const htmlAttr = el.getAttribute('g-html');
+    if (htmlAttr) {
+        const applyHtml = () => {
+            const value = ctx.eval(htmlAttr);
+            el.innerHTML = String(value ?? '');
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyHtml);
+        }
+        else {
+            applyHtml();
+        }
+    }
+    // Process g-bind:* attributes
+    const bindAttrs = [...el.attributes].filter(a => a.name.startsWith('g-bind:'));
+    for (const attr of bindAttrs) {
+        const targetAttr = attr.name.slice('g-bind:'.length);
+        const valueExpr = attr.value;
+        const applyBinding = () => {
+            const value = ctx.eval(valueExpr);
+            if (value === null || value === undefined) {
+                el.removeAttribute(targetAttr);
+            }
+            else {
+                el.setAttribute(targetAttr, String(value));
+            }
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyBinding);
+        }
+        else {
+            applyBinding();
+        }
+    }
+    return scope;
+}
+/**
+ * Process an element tree (element and all descendants).
+ *
+ * @remarks
+ * Recursively processes directives on an element and all its children.
+ * Each child gets its own scope that inherits from the parent.
+ *
+ * @param el - The root element to process
+ * @param parentScope - The parent scope
+ * @param mode - Server or client mode
+ * @param options - Processing options (existingScope only applies to root element)
+ */
+export function processElementTree(el, parentScope, mode, options = {}) {
+    // Process the root element
+    const scope = processElementDirectives(el, parentScope, mode, options);
+    // Process children recursively (they get fresh child scopes)
+    for (const child of el.children) {
+        processElementTree(child, scope, mode, { skipStructural: true });
+    }
+}

package/dist/scope.js

@@ -110,6 +110,10 @@ fn, options) {
             const parentScope = findParentScope(this);
             // Create this element's scope
             const scope = createElementScope(this, parentScope);
+            // Apply assigned values to scope
+            if (options.assign) {
+                Object.assign(scope, options.assign);
+            }
             // Create context for expression evaluation
             const ctx = createContext(Mode.CLIENT, scope);
             // Resolve dependencies using shared resolver

package/dist/server/render.js

@@ -3,7 +3,7 @@
  *
  * @packageDocumentation
  */
-import { parseHTML } from 'linkedom';
+import { parseHTML } from 'linkedom/worker';
 import { Mode, DirectivePriority, getDirective } from '../types.js';
 import { createContext } from '../context.js';
 import { processNativeSlot } from '../directives/slot.js';
@@ -26,11 +26,26 @@ function getSelector(registry) {
         const directiveSelectors = [...registry.keys()].map(n => `[g-${n}]`);
         // Also match native <slot> elements
         directiveSelectors.push('slot');
+        // Match g-scope for inline scope initialization
+        directiveSelectors.push('[g-scope]');
         selector = directiveSelectors.join(',');
         selectorCache.set(registry, selector);
     }
     return selector;
 }
+/**
+ * Check if element has any g-bind:* attributes.
+ *
+ * @internal
+ */
+function hasBindAttributes(el) {
+    for (const attr of el.attributes) {
+        if (attr.name.startsWith('g-bind:')) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Register a directive in the registry.
  *
@@ -120,6 +135,10 @@ export async function render(html, state, registry) {
                 const matches = el.matches(selector) ? [el] : [];
                 const descendants = [...el.querySelectorAll(selector)];
                 for (const match of [...matches, ...descendants]) {
+                    // Skip elements inside template content (used as placeholders)
+                    if (match.closest('template')) {
+                        continue;
+                    }
                     // Handle native <slot> elements
                     if (match.tagName === 'SLOT') {
                         index.push({
@@ -204,6 +223,27 @@ export async function render(html, state, registry) {
             const directives = byElement.get(el);
             // Sort directives on this element by priority (higher first)
             directives.sort((a, b) => b.priority - a.priority);
+            // Process g-scope first (inline scope initialization)
+            const scopeAttr = el.getAttribute('g-scope');
+            if (scopeAttr) {
+                const scopeValues = ctx.eval(scopeAttr);
+                if (scopeValues && typeof scopeValues === 'object') {
+                    Object.assign(state, scopeValues);
+                }
+            }
+            // Process g-bind:* attributes (dynamic attribute binding)
+            for (const attr of [...el.attributes]) {
+                if (attr.name.startsWith('g-bind:')) {
+                    const targetAttr = attr.name.slice('g-bind:'.length);
+                    const value = ctx.eval(attr.value);
+                    if (value === null || value === undefined) {
+                        el.removeAttribute(targetAttr);
+                    }
+                    else {
+                        el.setAttribute(targetAttr, String(value));
+                    }
+                }
+            }
             for (const item of directives) {
                 // Check if element was disconnected by a previous directive (e.g., g-for replacing it)
                 if (!item.el.isConnected) {

package/dist/types.d.ts

@@ -50,7 +50,7 @@ export interface InjectableRegistry {
     /** Function to evaluate expressions against state */
     $eval: EvalFn;
     /** Local reactive state object (isolated per element) */
-    $state: Record<string, unknown>;
+    $scope: Record<string, unknown>;
     /** Root reactive state object (shared across all elements) */
     $rootState: Record<string, unknown>;
     /** Template registry for g-template directive */
@@ -72,7 +72,7 @@ type ContextKeyValue<K> = K extends ContextKey<infer V> ? V : never;
  *
  * @example
  * ```ts
- * type Args = MapInjectables<['$element', '$state']>;
+ * type Args = MapInjectables<['$element', '$scope']>;
  * // => [Element, Record<string, unknown>]
  *
  * // With context keys
@@ -153,7 +153,7 @@ export interface DirectiveMeta<T = InjectableRegistry> {
      * - `$expr`: The expression string from the attribute
      * - `$element`: The target DOM element
      * - `$eval`: Function to evaluate expressions: `(expr) => value`
-     * - `$state`: Local reactive state object (isolated per element)
+     * - `$scope`: Local reactive state object (isolated per element)
      * - Any registered service names
      * - Any `ContextKey` for typed context resolution
      * - Any names provided by ancestor directives via `$context`
@@ -161,7 +161,7 @@ export interface DirectiveMeta<T = InjectableRegistry> {
      * @example
      * ```ts
      * // String-based injection
-     * myDirective.$inject = ['$element', '$state'];
+     * myDirective.$inject = ['$element', '$scope'];
      *
      * // With typed context keys
      * myDirective.$inject = ['$element', SlotContentContext];
@@ -172,16 +172,16 @@ export interface DirectiveMeta<T = InjectableRegistry> {
      * Names this directive exposes as context to descendants.
      *
      * @remarks
-     * When a directive declares `$context`, its `$state` becomes
+     * When a directive declares `$context`, its `$scope` becomes
      * available to descendant directives under those names.
      * Useful for passing state through isolate scope boundaries.
      *
      * @example
      * ```ts
-     * const themeProvider: Directive = ($state) => {
-     *   $state.mode = 'dark';
+     * const themeProvider: Directive = ($scope) => {
+     *   $scope.mode = 'dark';
      * };
-     * themeProvider.$inject = ['$state'];
+     * themeProvider.$inject = ['$scope'];
      * themeProvider.$context = ['theme'];
      *
      * // Descendants can inject 'theme'
@@ -338,7 +338,7 @@ export interface DirectiveOptions {
      * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
      * const UserContext = createContextKey<{ name: string }>('User');
      *
-     * directive('themed-greeting', ($element, $state, theme, user) => {
+     * directive('themed-greeting', ($element, $scope, theme, user) => {
      *   // theme and user are resolved from the using array
      *   $element.textContent = `Hello ${user.name}!`;
      *   $element.className = theme.mode;
@@ -348,6 +348,39 @@ export interface DirectiveOptions {
      * ```
      */
     using?: ContextKey<unknown>[];
+    /**
+     * Values to assign to the directive's scope.
+     *
+     * @remarks
+     * Requires `scope: true`. Assigns the provided values to the
+     * directive's scope, making them available in expressions.
+     *
+     * Useful for injecting external values (like styles) that should
+     * be accessible in templates without manual `$scope` assignment.
+     *
+     * @example
+     * ```ts
+     * import styles from './button.css';
+     *
+     * directive('my-button', handler, {
+     *   scope: true,
+     *   assign: { $styles: styles }
+     * });
+     *
+     * // In template:
+     * // <div g-class="$styles.container">...</div>
+     * ```
+     */
+    assign?: Record<string, unknown>;
+    /**
+     * Index signature for custom options.
+     *
+     * @remarks
+     * Allows libraries to pass additional options that gonia
+     * doesn't process directly. Libraries can create typed
+     * wrapper functions around `directive()` for type safety.
+     */
+    [key: string]: unknown;
 }
 /** Registered directive with options */
 export interface DirectiveRegistration {
@@ -372,8 +405,8 @@ export interface DirectiveRegistration {
  * @example
  * ```ts
  * // Directive with behavior
- * directive('todo-app', ($element, $state) => {
- *   $state.todos = [];
+ * directive('todo-app', ($element, $scope) => {
+ *   $scope.todos = [];
  * }, { scope: true });
  *
  * // Template-only directive

package/dist/types.js

@@ -49,8 +49,8 @@ const directiveRegistry = new Map();
  * @example
  * ```ts
  * // Directive with behavior
- * directive('todo-app', ($element, $state) => {
- *   $state.todos = [];
+ * directive('todo-app', ($element, $scope) => {
+ *   $scope.todos = [];
  * }, { scope: true });
  *
  * // Template-only directive
@@ -61,6 +61,11 @@ const directiveRegistry = new Map();
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function directive(name, fn, options = {}) {
+    // Validate: assign requires scope: true
+    if (options.assign && !options.scope) {
+        throw new Error(`Directive '${name}': 'assign' requires 'scope: true'. ` +
+            `To modify parent scope, use $scope in your directive function.`);
+    }
     directiveRegistry.set(name, { fn, options });
     // Register as custom element if name contains hyphen and scope is true
     if (fn && name.includes('-') && options.scope && typeof customElements !== 'undefined') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gonia",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A lightweight, SSR-first reactive UI library with declarative directives",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,7 @@
   "devDependencies": {
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
+    "conventional-changelog-cli": "^5.0.0",
     "jsdom": "^27.4.0",
     "typescript": "^5.7.0",
     "vite": "^6.4.0",
@@ -68,6 +69,8 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
+    "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
   }
 }