@getforma/core 0.3.1 → 0.6.1

package/dist/index.d.cts

@@ -16,6 +16,11 @@ declare function createEffect(fn: () => void | (() => void)): () => void;
 /**
  * Create a lazy, cached computed value.
  *
+ * Note: Unlike SolidJS's createComputed (which is an eager synchronous
+ * side effect), this is a lazy cached derivation — equivalent to
+ * SolidJS's createMemo. Both createComputed and createMemo in FormaJS
+ * are identical.
+ *
  * ```ts
  * const [count, setCount] = createSignal(0);
  * const doubled = createComputed(() => count() * 2);
@@ -39,6 +44,11 @@ declare function createComputed<T>(fn: () => T): () => T;
  * Create a memoized computed value.
  * Identical to `createComputed` — provided for React/SolidJS familiarity.
  *
+ * Note: Unlike SolidJS's createComputed (which is an eager synchronous
+ * side effect), both createComputed and createMemo in FormaJS are lazy
+ * cached derivations — equivalent to SolidJS's createMemo. They are
+ * identical.
+ *
  * The computation runs lazily and caches the result. It only recomputes
  * when a signal it reads during computation changes.
  *
@@ -380,6 +390,7 @@ declare function cleanup(el: Element): void;
  * )
  * ```
  */
+declare function h(tag: (props: Record<string, unknown>) => unknown, props?: Record<string, unknown> | null, ...children: unknown[]): Node;
 declare function h(tag: typeof Fragment, props?: null, ...children: unknown[]): DocumentFragment;
 declare function h(tag: string, props?: Record<string, unknown> | null, ...children: unknown[]): HTMLElement;
 /**
@@ -473,12 +484,6 @@ interface CreateListOptions {
      */
     updateOnItemChange?: 'none' | 'rerender';
 }
-/**
- * Find the longest increasing subsequence.
- * Returns indices into the input array.
- * O(n log n) time, O(n) space.
- */
-declare function longestIncreasingSubsequence(arr: number[]): number[];
 /**
  * Reconcile a DOM parent's children to match a new array of items.
  * Uses keyed reconciliation with LIS for minimum DOM operations.
@@ -712,8 +717,20 @@ declare function hydrateIsland(component: () => unknown, target: Element): Eleme
  * loads props (inline or script_tag), and hydrates each island inside
  * an independent createRoot scope with try/catch error isolation.
  */
-/** Function that creates a component's DOM tree (same for CSR and hydration). */
-type IslandHydrateFn = (props: Record<string, unknown> | null) => unknown;
+/**
+ * Function that hydrates an island.
+ *
+ * @param el     The root element of the island (`[data-forma-island]`).
+ *               Useful for layout measurement, focus management, CSS class
+ *               toggling, third-party library init, or reading extra `data-*`
+ *               attributes from the server-rendered shell.
+ * @param props  Parsed props from `data-forma-props` (inline or script block),
+ *               or `null` if no props were provided.
+ * @returns      A component tree (from `h()` calls) for descriptor-based
+ *               hydration, or `undefined` for imperative islands that set up
+ *               their own effects.
+ */
+type IslandHydrateFn = (el: HTMLElement, props: Record<string, unknown> | null) => unknown;
 /**
  * Discover and activate all SSR-rendered islands on the page.
  *
@@ -723,6 +740,21 @@ type IslandHydrateFn = (props: Record<string, unknown> | null) => unknown;
  * @param registry  Map of component names to hydration functions.
  */
 declare function activateIslands(registry: Record<string, IslandHydrateFn>): void;
+/**
+ * Dispose a single island, tearing down its reactive root and all effects.
+ *
+ * Safe to call multiple times (idempotent). Sets `data-forma-status` to
+ * `"disposed"` so the island can be distinguished from active/error states.
+ */
+declare function deactivateIsland(el: HTMLElement): void;
+/**
+ * Dispose ALL active islands under a root element (or the whole document).
+ *
+ * Use this when swapping module content — e.g., replacing the contents of
+ * a `<forma-stage>` Shadow DOM during AI generation. Prevents leaked effects
+ * and event listeners from accumulating across swaps.
+ */
+declare function deactivateAllIslands(root?: Element | Document): void;
 
 /**
  * Forma Component - Define
@@ -1407,4 +1439,4 @@ declare function renderLocal(slotsJson: string): Promise<string>;
 /** Fragment render (single island) via WASM. */
 declare function renderIsland(slotsJson: string, islandId: number): Promise<string>;
 
-export { $, $$, $$serverFunction, type Action, type ActionOptions, Fragment, type IslandHydrateFn, type MutationResponse, type RPCRequest, type RPCResponse, activateIslands, addClass, applyRevalidation, batch, children, cleanup, closest, createAction, createBus, createComputed, createContext, createEffect, createErrorBoundary, createFetch, createHistory, createIndexedDB, createList, createLocalStorage, createMemo, createPortal, createRPCMiddleware, createReducer, createRef, createResource, createRoot, createSSE, createSessionStorage, createShow, createStore, createSuspense, createSwitch, createText, createWebSocket, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, fragment, getRegisteredEndpoints, getServerFunction, h, handleRPC, hydrateIsland, inject, longestIncreasingSubsequence, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, registerResource, registerServerFunction, removeClass, renderIsland, renderLocal, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, untrack, withRevalidation };
+export { $, $$, $$serverFunction, type Action, type ActionOptions, Fragment, type IslandHydrateFn, type MutationResponse, type RPCRequest, type RPCResponse, activateIslands, addClass, applyRevalidation, batch, children, cleanup, closest, createAction, createBus, createComputed, createContext, createEffect, createErrorBoundary, createFetch, createHistory, createIndexedDB, createList, createLocalStorage, createMemo, createPortal, createRPCMiddleware, createReducer, createRef, createResource, createRoot, createSSE, createSessionStorage, createShow, createStore, createSuspense, createSwitch, createText, createWebSocket, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, fragment, getRegisteredEndpoints, getServerFunction, h, handleRPC, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, registerResource, registerServerFunction, removeClass, renderIsland, renderLocal, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, untrack, withRevalidation };

package/dist/index.d.ts

@@ -16,6 +16,11 @@ declare function createEffect(fn: () => void | (() => void)): () => void;
 /**
  * Create a lazy, cached computed value.
  *
+ * Note: Unlike SolidJS's createComputed (which is an eager synchronous
+ * side effect), this is a lazy cached derivation — equivalent to
+ * SolidJS's createMemo. Both createComputed and createMemo in FormaJS
+ * are identical.
+ *
  * ```ts
  * const [count, setCount] = createSignal(0);
  * const doubled = createComputed(() => count() * 2);
@@ -39,6 +44,11 @@ declare function createComputed<T>(fn: () => T): () => T;
  * Create a memoized computed value.
  * Identical to `createComputed` — provided for React/SolidJS familiarity.
  *
+ * Note: Unlike SolidJS's createComputed (which is an eager synchronous
+ * side effect), both createComputed and createMemo in FormaJS are lazy
+ * cached derivations — equivalent to SolidJS's createMemo. They are
+ * identical.
+ *
  * The computation runs lazily and caches the result. It only recomputes
  * when a signal it reads during computation changes.
  *
@@ -380,6 +390,7 @@ declare function cleanup(el: Element): void;
  * )
  * ```
  */
+declare function h(tag: (props: Record<string, unknown>) => unknown, props?: Record<string, unknown> | null, ...children: unknown[]): Node;
 declare function h(tag: typeof Fragment, props?: null, ...children: unknown[]): DocumentFragment;
 declare function h(tag: string, props?: Record<string, unknown> | null, ...children: unknown[]): HTMLElement;
 /**
@@ -473,12 +484,6 @@ interface CreateListOptions {
      */
     updateOnItemChange?: 'none' | 'rerender';
 }
-/**
- * Find the longest increasing subsequence.
- * Returns indices into the input array.
- * O(n log n) time, O(n) space.
- */
-declare function longestIncreasingSubsequence(arr: number[]): number[];
 /**
  * Reconcile a DOM parent's children to match a new array of items.
  * Uses keyed reconciliation with LIS for minimum DOM operations.
@@ -712,8 +717,20 @@ declare function hydrateIsland(component: () => unknown, target: Element): Eleme
  * loads props (inline or script_tag), and hydrates each island inside
  * an independent createRoot scope with try/catch error isolation.
  */
-/** Function that creates a component's DOM tree (same for CSR and hydration). */
-type IslandHydrateFn = (props: Record<string, unknown> | null) => unknown;
+/**
+ * Function that hydrates an island.
+ *
+ * @param el     The root element of the island (`[data-forma-island]`).
+ *               Useful for layout measurement, focus management, CSS class
+ *               toggling, third-party library init, or reading extra `data-*`
+ *               attributes from the server-rendered shell.
+ * @param props  Parsed props from `data-forma-props` (inline or script block),
+ *               or `null` if no props were provided.
+ * @returns      A component tree (from `h()` calls) for descriptor-based
+ *               hydration, or `undefined` for imperative islands that set up
+ *               their own effects.
+ */
+type IslandHydrateFn = (el: HTMLElement, props: Record<string, unknown> | null) => unknown;
 /**
  * Discover and activate all SSR-rendered islands on the page.
  *
@@ -723,6 +740,21 @@ type IslandHydrateFn = (props: Record<string, unknown> | null) => unknown;
  * @param registry  Map of component names to hydration functions.
  */
 declare function activateIslands(registry: Record<string, IslandHydrateFn>): void;
+/**
+ * Dispose a single island, tearing down its reactive root and all effects.
+ *
+ * Safe to call multiple times (idempotent). Sets `data-forma-status` to
+ * `"disposed"` so the island can be distinguished from active/error states.
+ */
+declare function deactivateIsland(el: HTMLElement): void;
+/**
+ * Dispose ALL active islands under a root element (or the whole document).
+ *
+ * Use this when swapping module content — e.g., replacing the contents of
+ * a `<forma-stage>` Shadow DOM during AI generation. Prevents leaked effects
+ * and event listeners from accumulating across swaps.
+ */
+declare function deactivateAllIslands(root?: Element | Document): void;
 
 /**
  * Forma Component - Define
@@ -1407,4 +1439,4 @@ declare function renderLocal(slotsJson: string): Promise<string>;
 /** Fragment render (single island) via WASM. */
 declare function renderIsland(slotsJson: string, islandId: number): Promise<string>;
 
-export { $, $$, $$serverFunction, type Action, type ActionOptions, Fragment, type IslandHydrateFn, type MutationResponse, type RPCRequest, type RPCResponse, activateIslands, addClass, applyRevalidation, batch, children, cleanup, closest, createAction, createBus, createComputed, createContext, createEffect, createErrorBoundary, createFetch, createHistory, createIndexedDB, createList, createLocalStorage, createMemo, createPortal, createRPCMiddleware, createReducer, createRef, createResource, createRoot, createSSE, createSessionStorage, createShow, createStore, createSuspense, createSwitch, createText, createWebSocket, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, fragment, getRegisteredEndpoints, getServerFunction, h, handleRPC, hydrateIsland, inject, longestIncreasingSubsequence, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, registerResource, registerServerFunction, removeClass, renderIsland, renderLocal, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, untrack, withRevalidation };
+export { $, $$, $$serverFunction, type Action, type ActionOptions, Fragment, type IslandHydrateFn, type MutationResponse, type RPCRequest, type RPCResponse, activateIslands, addClass, applyRevalidation, batch, children, cleanup, closest, createAction, createBus, createComputed, createContext, createEffect, createErrorBoundary, createFetch, createHistory, createIndexedDB, createList, createLocalStorage, createMemo, createPortal, createRPCMiddleware, createReducer, createRef, createResource, createRoot, createSSE, createSessionStorage, createShow, createStore, createSuspense, createSwitch, createText, createWebSocket, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, fragment, getRegisteredEndpoints, getServerFunction, h, handleRPC, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, registerResource, registerServerFunction, removeClass, renderIsland, renderLocal, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, untrack, withRevalidation };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { internalEffect, createRoot, hydrateIsland, untrack, createEffect, pushSuspenseContext, popSuspenseContext, __DEV__, batch } from './chunk-5H52PKGF.js';
-export { Fragment, batch, cleanup, createEffect, createList, createMemo, createReducer, createRef, createResource, createRoot, createShow, fragment, h, hydrateIsland, longestIncreasingSubsequence, on, onCleanup, onError, reconcileList, untrack } from './chunk-5H52PKGF.js';
-import { createSignal, createValueSignal } from './chunk-KX5WRZH7.js';
-export { createComputed, createSignal } from './chunk-KX5WRZH7.js';
+import { internalEffect, createRoot, hydrateIsland, untrack, createEffect, pushSuspenseContext, popSuspenseContext, __DEV__, reportError, batch } from './chunk-TKGUHASG.js';
+export { Fragment, batch, cleanup, createEffect, createList, createMemo, createReducer, createRef, createResource, createRoot, createShow, fragment, h, hydrateIsland, on, onCleanup, onError, reconcileList, untrack } from './chunk-TKGUHASG.js';
+import { createSignal } from './chunk-DPSAVBCP.js';
+export { createComputed, createSignal } from './chunk-DPSAVBCP.js';
 
 // src/dom/text.ts
 function createText(value) {
@@ -243,9 +243,6 @@ function activateIslands(registry2) {
       continue;
     }
     const trigger = root.getAttribute("data-forma-hydrate") || "load";
-    if (trigger === "interaction" || trigger === "idle") {
-      if (__DEV__) console.warn(`[forma] Trigger "${trigger}" not yet implemented for island "${componentName}" (id=${id}), falling back to load`);
-    }
     if (trigger === "visible") {
       const observer = new IntersectionObserver(
         (entries) => {
@@ -258,18 +255,47 @@ function activateIslands(registry2) {
         { rootMargin: "200px" }
       );
       observer.observe(root);
+    } else if (trigger === "idle") {
+      const hydrate = () => hydrateIslandRoot(root, id, componentName, hydrateFn, sharedProps);
+      if (typeof requestIdleCallback === "function") {
+        requestIdleCallback(hydrate);
+      } else {
+        setTimeout(hydrate, 200);
+      }
+    } else if (trigger === "interaction") {
+      const hydrate = () => {
+        root.removeEventListener("pointerdown", hydrate, true);
+        root.removeEventListener("focusin", hydrate, true);
+        hydrateIslandRoot(root, id, componentName, hydrateFn, sharedProps);
+      };
+      root.addEventListener("pointerdown", hydrate, { capture: true, once: true });
+      root.addEventListener("focusin", hydrate, { capture: true, once: true });
     } else {
       hydrateIslandRoot(root, id, componentName, hydrateFn, sharedProps);
     }
   }
 }
+function deactivateIsland(el) {
+  const dispose = el.__formaDispose;
+  if (typeof dispose === "function") {
+    dispose();
+    delete el.__formaDispose;
+    el.setAttribute("data-forma-status", "disposed");
+  }
+}
+function deactivateAllIslands(root = document) {
+  const islands = root.querySelectorAll('[data-forma-status="active"]');
+  for (const island of islands) {
+    deactivateIsland(island);
+  }
+}
 function hydrateIslandRoot(root, id, componentName, hydrateFn, sharedProps) {
   try {
     const props = loadIslandProps(root, id, sharedProps);
     root.setAttribute("data-forma-status", "hydrating");
     let activeRoot = root;
     createRoot((dispose) => {
-      activeRoot = hydrateIsland(() => hydrateFn(props), root);
+      activeRoot = hydrateIsland(() => hydrateFn(root, props), root);
       activeRoot.__formaDispose = dispose;
     });
     activeRoot.setAttribute("data-forma-status", "active");
@@ -322,13 +348,15 @@ function defineComponent(setupOrDef) {
       for (const cb of ctx.unmountCallbacks) {
         try {
           cb();
-        } catch {
+        } catch (e) {
+          reportError(e, "onUnmount");
         }
       }
       for (const d of ctx.disposers) {
         try {
           d();
-        } catch {
+        } catch (e) {
+          reportError(e, "component disposer");
         }
       }
       ctx.disposers.length = 0;
@@ -342,7 +370,8 @@ function defineComponent(setupOrDef) {
         if (typeof cleanup2 === "function") {
           ctx.unmountCallbacks.push(cleanup2);
         }
-      } catch {
+      } catch (e) {
+        reportError(e, "onMount");
       }
     }
     return dom;
@@ -616,9 +645,9 @@ function createHistory(source, options) {
   const maxLength = options?.maxLength ?? 100;
   let _stack = [sourceGet()];
   let _cursor = 0;
-  const [stackSignal, setStackSignal] = createValueSignal([..._stack]);
-  const [cursorSignal, setCursorSignal] = createValueSignal(_cursor);
-  const [stackLenSignal, setStackLenSignal] = createValueSignal(_stack.length);
+  const [stackSignal, setStackSignal] = createSignal([..._stack]);
+  const [cursorSignal, setCursorSignal] = createSignal(_cursor);
+  const [stackLenSignal, setStackLenSignal] = createSignal(_stack.length);
   function syncSignals() {
     batch(() => {
       setStackSignal([..._stack]);
@@ -1315,8 +1344,8 @@ function createWebSocket(url, options) {
 
 // src/server/action.ts
 function createAction(serverFn, options) {
-  const [pending, setPending] = createValueSignal(false);
-  const [error, setError] = createValueSignal(void 0);
+  const [pending, setPending] = createSignal(false);
+  const [error, setError] = createSignal(void 0);
   const action = async (...args) => {
     setPending(true);
     setError(void 0);
@@ -1507,6 +1536,6 @@ async function renderIsland(slotsJson, islandId) {
   return wasm.render_island(ir, slotsJson, islandId);
 }
 
-export { $, $$, $$serverFunction, activateIslands, addClass, applyRevalidation, children, closest, createAction, createBus, createContext, createErrorBoundary, createFetch, createHistory, createIndexedDB, createLocalStorage, createPortal, createRPCMiddleware, createSSE, createSessionStorage, createStore, createSuspense, createSwitch, createText, createWebSocket, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, getRegisteredEndpoints, getServerFunction, handleRPC, inject, mount, nextSibling, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, registerResource, registerServerFunction, removeClass, renderIsland, renderLocal, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, withRevalidation };
+export { $, $$, $$serverFunction, activateIslands, addClass, applyRevalidation, children, closest, createAction, createBus, createContext, createErrorBoundary, createFetch, createHistory, createIndexedDB, createLocalStorage, createPortal, createRPCMiddleware, createSSE, createSessionStorage, createStore, createSuspense, createSwitch, createText, createWebSocket, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, enableAutoRevalidation, fetchJSON, getRegisteredEndpoints, getServerFunction, handleRPC, inject, mount, nextSibling, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, registerResource, registerServerFunction, removeClass, renderIsland, renderLocal, setAttr, setHTML, setHTMLUnsafe, setStyle, setText, siblings, toggleClass, trackDisposer, unprovide, unregisterResource, withRevalidation };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map