@getforma/core 0.6.1 → 0.8.2

package/README.md

@@ -162,14 +162,39 @@ mount(() => <Counter />, '#app');
 
 ## CDN Usage
 
-Both long and short filenames are provided. They are identical files — use whichever you prefer:
+### Script tag (IIFE — auto-initializes)
 
-| Build | URL |
-|-------|-----|
-| **Standard** (recommended) | `unpkg.com/@getforma/core/dist/formajs-runtime.global.js` |
-| Standard (short alias) | `unpkg.com/@getforma/core/dist/forma-runtime.js` |
-| **CSP-safe** (no `new Function`) | `unpkg.com/@getforma/core/dist/formajs-runtime-hardened.global.js` |
-| CSP-safe (short alias) | `unpkg.com/@getforma/core/dist/forma-runtime-csp.js` |
+```html
+<!-- unpkg -->
+<script src="https://unpkg.com/@getforma/core@0.8.1/dist/formajs-runtime.global.js"></script>
+
+<!-- jsDelivr (faster globally) -->
+<script src="https://cdn.jsdelivr.net/npm/@getforma/core@0.8.1/dist/formajs-runtime.global.js"></script>
+```
+
+### ESM import (no bundler, modern browsers)
+
+```html
+<script type="module">
+  import { createSignal, h, mount } from 'https://cdn.jsdelivr.net/npm/@getforma/core@0.8.1/dist/index.js';
+
+  const [count, setCount] = createSignal(0);
+  mount(() => h('button', { onClick: () => setCount(count() + 1) }, () => `${count()}`), '#app');
+</script>
+```
+
+### All CDN builds
+
+| Build | Filename |
+|-------|----------|
+| **Standard** (recommended) | `formajs-runtime.global.js` |
+| **CSP-safe** (no `new Function`) | `formajs-runtime-hardened.global.js` |
+| Standard (short alias) | `forma-runtime.js` |
+| CSP-safe (short alias) | `forma-runtime-csp.js` |
+
+Available from both `unpkg.com/@getforma/core@VERSION/dist/` and `cdn.jsdelivr.net/npm/@getforma/core@VERSION/dist/`.
+
+For production, always pin the version (e.g., `@0.8.1`). Unversioned URLs resolve to latest.
 
 > The CSP build uses a hand-written expression parser and never calls `new Function`.
 > It supports most common patterns. See [examples/csp](./examples/csp) for a working demo.
@@ -192,6 +217,45 @@ batch(() => {
 });
 ```
 
+#### Custom Equality
+
+Skip updates when the new value is equal to the current value:
+
+```typescript
+const [pos, setPos] = createSignal(
+  { x: 0, y: 0 },
+  { equals: (a, b) => a.x === b.x && a.y === b.y },
+);
+
+setPos({ x: 0, y: 0 }); // skipped — values are equal
+setPos({ x: 1, y: 0 }); // applied — values differ
+```
+
+#### Computed with Previous Value
+
+The computed getter receives the previous value for efficient diffing:
+
+```typescript
+const changes = createComputed((prev) => {
+  const current = items();
+  if (prev) console.log(`${prev.length} → ${current.length} items`);
+  return current;
+});
+```
+
+#### Reactive Introspection
+
+Type guards and utilities from alien-signals 3.x:
+
+```typescript
+import { isSignal, isComputed, getBatchDepth, trigger } from '@getforma/core';
+
+isSignal(count);           // true — is this a signal getter?
+isComputed(doubled);       // true — is this a computed value?
+getBatchDepth();           // 0 outside batch, 1+ inside
+trigger(doubled);          // force recomputation even if deps unchanged
+```
+
 ### Conditional Rendering
 
 ```typescript
@@ -240,12 +304,17 @@ const [state, setState] = createStore({
   items: [1, 2, 3],
 });
 
-// Read reactively
+// Read reactively — tracked at the exact property path
 state.user.name;        // 'Alice'
+state.items[0];         // 1
+
+// Setter API — partial object merge (batched)
+setState({ user: { ...state.user, name: 'Bob' } });
+setState(prev => ({ items: [...prev.items, 4] }));
 
-// Mutate — only affected subscribers update
-setState('user', 'name', 'Bob');
-setState('items', items => [...items, 4]);
+// Or mutate directly via proxy — only affected subscribers update
+state.user.name = 'Bob';          // only "user.name" subscribers notified
+state.items.push(4);              // array mutation batched automatically
 ```
 
 ### Components
@@ -332,6 +401,40 @@ provide(ThemeCtx, 'dark');
 const theme = inject(ThemeCtx); // 'dark'
 ```
 
+### History (undo/redo)
+
+```typescript
+import { createHistory } from '@getforma/core';
+
+const [state, setState, { undo, redo, canUndo, canRedo }] = createHistory({ text: '' });
+
+setState({ text: 'hello' });
+setState({ text: 'hello world' });
+
+undo();              // state.text === 'hello'
+canUndo();           // true
+redo();              // state.text === 'hello world'
+```
+
+### Reducer
+
+```typescript
+import { createReducer } from '@getforma/core';
+
+const [state, dispatch] = createReducer(
+  (state, action) => {
+    switch (action.type) {
+      case 'INCREMENT': return { count: state.count + 1 };
+      case 'DECREMENT': return { count: state.count - 1 };
+      default: return state;
+    }
+  },
+  { count: 0 },
+);
+
+dispatch({ type: 'INCREMENT' }); // state() === { count: 1 }
+```
+
 ## Islands Architecture
 
 For server-rendered HTML, activate independent interactive regions. Each island callback receives the root DOM element and parsed props, then returns a component tree — the same `h()` calls you'd use for client-side rendering. The hydration system walks the descriptor tree against the existing SSR DOM, attaching event handlers and reactive bindings without recreating elements.
@@ -432,11 +535,14 @@ FormaJS shares Solid's core insight — fine-grained signals updating the real D
 | **CSP** | Relies on compiler output | Hand-written expression parser; hardened build has no `new Function()` |
 | **Islands** | Via [solid-start](https://start.solidjs.com/) meta-framework | Built-in `activateIslands()` — no meta-framework needed |
 | **Ecosystem** | Mature (router, meta-framework, devtools) | Minimal — reactive core only, you bring the architecture |
+| **SSR runtime** | Node.js required | Node.js via `renderToString`, or Rust walker (no JS runtime on the server) |
 | **Size** | ~7KB | ~15KB (includes runtime parser, stores, SSR) |
 
-**When to choose FormaJS:** You want to progressively enhance server-rendered HTML, need CSP compliance without a build step, or prefer a single library that scales from a `<script>` tag to a full SSR pipeline.
+**When to choose FormaJS:** You want islands hydration built into the library, not bolted on through a meta-framework. You need CSP compliance without a build step. You want three entry points (CDN, hyperscript, JSX) sharing one signal graph. Or you're building on a Rust backend and want your frontend reactive layer to integrate natively with the server stack.
+
+**When to choose Solid:** You want a mature JavaScript ecosystem with routing, SSR meta-framework (SolidStart), devtools, and community-built component libraries. Your backend is Node.js and you want SSR in the same language as your frontend.
 
-**When to choose Solid:** You want a mature ecosystem with routing, SSR meta-framework, and community-built component libraries.
+> FormaJS is the reactive layer of the [Forma stack](https://getforma.dev). The full pipeline compiles components to a binary IR (FMIR), renders them in Rust via `forma-ir`, and serves pages through `forma-server` — SSR without Node.js, binary IR over the wire, deployed for ~$18/month.
 
 ## Stability
 
@@ -444,7 +550,8 @@ Some features are more battle-tested than others:
 
 | Feature | Status | Notes |
 |---------|--------|-------|
-| Signals (`createSignal`, `createEffect`, `createComputed`, `batch`) | **Stable** | Core primitive, well-tested |
+| Signals (`createSignal`, `createEffect`, `createComputed`, `batch`) | **Stable** | Core primitive, well-tested. Custom `equals` option supported. |
+| Reactive introspection (`isSignal`, `isComputed`, `trigger`, `getBatchDepth`) | **Stable** | alien-signals 3.x type guards |
 | `h()` / JSX rendering | **Stable** | |
 | `mount()`, `createShow`, `createSwitch`, `createList` | **Stable** | |
 | HTML Runtime (`data-*` directives) | **Stable** | Expression parser covers common patterns |
@@ -452,7 +559,10 @@ Some features are more battle-tested than others:
 | `createStore` (deep reactivity) | **Stable** | |
 | Components (`defineComponent`, lifecycle) | **Stable** | |
 | Context (`createContext`, `provide`, `inject`) | **Stable** | |
-| Islands (`activateIslands`) | **Stable** | 10 activation + 88 hydration tests |
+| Islands (`activateIslands`, disposal, triggers) | **Stable** | 10 activation + 88 hydration + 10 trigger tests |
+| `createHistory` (undo/redo) | **Stable** | |
+| `createReducer` | **Stable** | 8 tests |
+| `data-fetch`, `data-transition:*` | **Stable** | Fully implemented in HTML Runtime |
 | SSR (`renderToString`, `renderToStream`) | **Beta** | Functional, API may evolve |
 | TC39 Signals compat (`Signal.State`, `Signal.Computed`) | **Beta** | 9 tests, but tracks an evolving TC39 proposal |
 

package/dist/chunk-3U57L2TY.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+var alienSignals = require('alien-signals');
+
+// src/reactive/signal.ts
+function applySignalSet(s, v, equals) {
+  if (typeof v !== "function") {
+    if (equals) {
+      const prevSub2 = alienSignals.setActiveSub(void 0);
+      const prev2 = s();
+      alienSignals.setActiveSub(prevSub2);
+      if (equals(prev2, v)) return;
+    }
+    s(v);
+    return;
+  }
+  const prevSub = alienSignals.setActiveSub(void 0);
+  const prev = s();
+  alienSignals.setActiveSub(prevSub);
+  const next = v(prev);
+  if (equals && equals(prev, next)) return;
+  s(next);
+}
+function createSignal(initialValue, options) {
+  const s = alienSignals.signal(initialValue);
+  const getter = s;
+  const eq = options?.equals;
+  const setter = (v) => applySignalSet(s, v, eq);
+  return [getter, setter];
+}
+function createComputed(fn) {
+  return alienSignals.computed(fn);
+}
+
+exports.createComputed = createComputed;
+exports.createSignal = createSignal;
+//# sourceMappingURL=chunk-3U57L2TY.cjs.map
+//# sourceMappingURL=chunk-3U57L2TY.cjs.map

package/dist/chunk-3U57L2TY.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/reactive/signal.ts","../src/reactive/computed.ts"],"names":["prevSub","setActiveSub","prev","createRawSignal","rawComputed"],"mappings":";;;;;AAkEA,SAAS,cAAA,CACP,CAAA,EACA,CAAA,EACA,MAAA,EACM;AACN,EAAA,IAAI,OAAO,MAAM,UAAA,EAAY;AAC3B,IAAA,IAAI,MAAA,EAAQ;AAEV,MAAA,MAAMA,QAAAA,GAAUC,0BAAa,MAAS,CAAA;AACtC,MAAA,MAAMC,QAAO,CAAA,EAAE;AACf,MAAAD,yBAAA,CAAaD,QAAO,CAAA;AACpB,MAAA,IAAI,MAAA,CAAOE,KAAAA,EAAM,CAAC,CAAA,EAAG;AAAA,IACvB;AACA,IAAA,CAAA,CAAE,CAAC,CAAA;AACH,IAAA;AAAA,EACF;AAGA,EAAA,MAAM,OAAA,GAAUD,0BAAa,MAAS,CAAA;AACtC,EAAA,MAAM,OAAO,CAAA,EAAE;AACf,EAAAA,yBAAA,CAAa,OAAO,CAAA;AACpB,EAAA,MAAM,IAAA,GAAQ,EAAqB,IAAI,CAAA;AACvC,EAAA,IAAI,MAAA,IAAU,MAAA,CAAO,IAAA,EAAM,IAAI,CAAA,EAAG;AAClC,EAAA,CAAA,CAAE,IAAI,CAAA;AACR;AAqBO,SAAS,YAAA,CAAgB,cAAiB,OAAA,EAA0E;AACzH,EAAA,MAAM,CAAA,GAAIE,oBAAmB,YAAY,CAAA;AACzC,EAAA,MAAM,MAAA,GAAS,CAAA;AACf,EAAA,MAAM,KAAK,OAAA,EAAS,MAAA;AACpB,EAAA,MAAM,SAA0B,CAAC,CAAA,KAA4B,cAAA,CAAe,CAAA,EAAG,GAAG,EAAE,CAAA;AAEpF,EAAA,OAAO,CAAC,QAAQ,MAAM,CAAA;AACxB;AC7EO,SAAS,eAAkB,EAAA,EAAuC;AACvE,EAAA,OAAOC,sBAAY,EAAE,CAAA;AACvB","file":"chunk-3U57L2TY.cjs","sourcesContent":["/**\n * Forma Reactive - Signal\n *\n * Fine-grained reactive primitive backed by alien-signals.\n * API: createSignal returns [getter, setter] tuple following SolidJS conventions.\n *\n * TC39 Signals equivalent: Signal.State\n */\n\nimport { signal as createRawSignal, setActiveSub } from 'alien-signals';\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\nexport type SignalGetter<T> = () => T;\nexport type SignalSetter<T> = (v: T | ((prev: T) => T)) => void;\n\nexport interface SignalOptions<T> {\n  /** Debug name — attached to getter in dev mode for devtools inspection. */\n  name?: string;\n  /**\n   * Custom equality check. When provided, the setter will read the current\n   * value and only update the signal if `equals(prev, next)` returns `false`.\n   *\n   * Default: none (alien-signals uses strict inequality `!==` internally).\n   *\n   * ```ts\n   * const [pos, setPos] = createSignal(\n   *   { x: 0, y: 0 },\n   *   { equals: (a, b) => a.x === b.x && a.y === b.y },\n   * );\n   *\n   * setPos({ x: 0, y: 0 }); // skipped — equals returns true\n   * setPos({ x: 1, y: 0 }); // applied — equals returns false\n   * ```\n   */\n  equals?: (prev: T, next: T) => boolean;\n}\n\n/**\n * Wrap a value so the setter treats it as a literal value, not a functional updater.\n *\n * When `T` is itself a function type, passing a function to the setter is\n * ambiguous -- it looks like a functional update (`prev => next`). Use\n * `value()` to disambiguate:\n *\n * ```ts\n * const [getFn, setFn] = createSignal<() => void>(() => console.log('a'));\n *\n * // BUG: interpreted as a functional update -- calls the arrow with prev\n * // setFn(() => console.log('b'));\n *\n * // Correct: wraps in a thunk so the setter stores it as-is\n * setFn(value(() => console.log('b')));\n * ```\n */\nexport function value<T>(v: T): () => T {\n  return () => v;\n}\n\ntype RawSignal<T> = {\n  (): T;\n  (value: T): void;\n};\n\nfunction applySignalSet<T>(\n  s: RawSignal<T>,\n  v: T | ((prev: T) => T),\n  equals?: (prev: T, next: T) => boolean,\n): void {\n  if (typeof v !== 'function') {\n    if (equals) {\n      // Read current value without tracking\n      const prevSub = setActiveSub(undefined);\n      const prev = s();\n      setActiveSub(prevSub);\n      if (equals(prev, v)) return; // skip — values are equal\n    }\n    s(v);\n    return;\n  }\n\n  // Functional update: read prev without tracking\n  const prevSub = setActiveSub(undefined);\n  const prev = s();\n  setActiveSub(prevSub);\n  const next = (v as (prev: T) => T)(prev);\n  if (equals && equals(prev, next)) return; // skip — values are equal\n  s(next);\n}\n\n/**\n * Create a reactive signal.\n *\n * ```ts\n * const [count, setCount] = createSignal(0);\n * console.log(count()); // 0\n * setCount(1);\n * setCount(prev => prev + 1);\n * ```\n *\n * With custom equality:\n *\n * ```ts\n * const [pos, setPos] = createSignal(\n *   { x: 0, y: 0 },\n *   { equals: (a, b) => a.x === b.x && a.y === b.y },\n * );\n * ```\n */\nexport function createSignal<T>(initialValue: T, options?: SignalOptions<T>): [get: SignalGetter<T>, set: SignalSetter<T>] {\n  const s = createRawSignal<T>(initialValue) as RawSignal<T>;\n  const getter = s as unknown as SignalGetter<T>;\n  const eq = options?.equals;\n  const setter: SignalSetter<T> = (v: T | ((prev: T) => T)) => applySignalSet(s, v, eq);\n\n  return [getter, setter];\n}\n","/**\n * Forma Reactive - Computed\n *\n * Lazy, cached derived value that participates in the reactive graph.\n * Backed by alien-signals for automatic dependency tracking\n * and cache invalidation.\n *\n * TC39 Signals equivalent: Signal.Computed\n */\n\nimport { computed as rawComputed } from 'alien-signals';\n\n/**\n * Create a lazy, cached computed value.\n *\n * Note: Unlike SolidJS's createComputed (which is an eager synchronous\n * side effect), this is a lazy cached derivation — equivalent to\n * SolidJS's createMemo. Both createComputed and createMemo in FormaJS\n * are identical.\n *\n * The getter receives the previous value as an argument, enabling\n * efficient diffing patterns without a separate signal:\n *\n * ```ts\n * const [count, setCount] = createSignal(0);\n * const doubled = createComputed(() => count() * 2);\n * console.log(doubled()); // 0\n * setCount(5);\n * console.log(doubled()); // 10\n * ```\n *\n * With previous value (for diffing):\n *\n * ```ts\n * const changes = createComputed((prev) => {\n *   const next = items();\n *   if (prev) console.log(`changed from ${prev.length} to ${next.length} items`);\n *   return next;\n * });\n * ```\n */\nexport function createComputed<T>(fn: (previousValue?: T) => T): () => T {\n  return rawComputed(fn);\n}\n"]}

package/dist/{chunk-TKGUHASG.js → chunk-N522P3G6.js}

@@ -1,14 +1,21 @@
-import { createComputed, createSignal } from './chunk-DPSAVBCP.js';
-import { effect, startBatch, endBatch, pauseTracking, resumeTracking } from 'alien-signals';
+import { createComputed, createSignal } from './chunk-OZCHIVAZ.js';
+import { effect, effectScope, startBatch, endBatch, setActiveSub } from 'alien-signals';
+export { getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, trigger } from 'alien-signals';
 
-// src/reactive/root.ts
 var currentRoot = null;
 var rootStack = [];
 function createRoot(fn) {
-  const scope = { disposers: [] };
+  const scope = { disposers: [], scopeDispose: null };
   rootStack.push(currentRoot);
   currentRoot = scope;
   const dispose = () => {
+    if (scope.scopeDispose) {
+      try {
+        scope.scopeDispose();
+      } catch {
+      }
+      scope.scopeDispose = null;
+    }
     for (const d of scope.disposers) {
       try {
         d();
@@ -17,14 +24,15 @@ function createRoot(fn) {
     }
     scope.disposers.length = 0;
   };
+  let result;
   try {
-    return fn(dispose);
+    scope.scopeDispose = effectScope(() => {
+      result = fn(dispose);
+    });
   } finally {
     currentRoot = rootStack.pop() ?? null;
-    if (rootStack.length === 0) {
-      rootStack.length = 0;
-    }
   }
+  return result;
 }
 function registerDisposer(dispose) {
   if (currentRoot) {
@@ -237,11 +245,11 @@ function batch(fn) {
   }
 }
 function untrack(fn) {
-  pauseTracking();
+  const prev = setActiveSub(void 0);
   try {
     return fn();
   } finally {
-    resumeTracking();
+    setActiveSub(prev);
   }
 }
 
@@ -1815,5 +1823,5 @@ function createList(items, keyFn, renderFn, options) {
 }
 
 export { Fragment, __DEV__, batch, cleanup, createEffect, createList, createMemo, createReducer, createRef, createResource, createRoot, createShow, fragment, h, hydrateIsland, internalEffect, on, onCleanup, onError, popSuspenseContext, pushSuspenseContext, reconcileList, reportError, untrack };
-//# sourceMappingURL=chunk-TKGUHASG.js.map
-//# sourceMappingURL=chunk-TKGUHASG.js.map
+//# sourceMappingURL=chunk-N522P3G6.js.map
+//# sourceMappingURL=chunk-N522P3G6.js.map