@bitstillery/mithril 3.0.0-AA → 3.0.2

package/README.md

@@ -1,18 +1,29 @@
 # @bitstillery/mithril
 
-> Mithril.js with **fine-grained reactivity**, **SSR hydration**, and **zero-dependency signals**.
+Mithril.js fork with fine-grained reactivity, SSR hydration, and built-in signals. Drop-in compatible with Mithril v2.x.
 
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+```bash
+bun add @bitstillery/mithril
+```
+
+## Why
 
-## The Problem
+Mithril.js uses global `m.redraw()` — one state change re-renders **everything**. This fork adds component-level reactivity via signals so only affected components update.
 
-Mithril.js uses global `m.redraw()`—one state change updates **all** components. This fork adds fine-grained reactivity: only components using changed state re-render.
+| Feature          | Original            | This Fork                       |
+| ---------------- | ------------------- | ------------------------------- |
+| Reactivity       | Global `m.redraw()` | Fine-grained component updates  |
+| State Management | Manual redraw calls | Signals with automatic tracking |
+| SSR              | No hydration        | State serialization + hydration |
+| TypeScript       | Community types     | Native                          |
 
-## What Makes This Different
+Signals are opt-in. Existing Mithril code works unchanged.
 
-### Signals
+**Docs**: [mithril.garage44.org](https://mithril.garage44.org)
 
-Fine-grained reactivity primitives with automatic dependency tracking. Zero-dependency implementation—no Preact Signals or other packages.
+## Signals
+
+Zero-dependency reactive primitives with automatic dependency tracking:
 
 ```typescript
 import {signal, computed, effect} from '@bitstillery/mithril'
@@ -20,71 +31,36 @@ import {signal, computed, effect} from '@bitstillery/mithril'
 const count = signal(0)
 const doubled = computed(() => count() * 2)
 
-effect(() => {
-    console.log(`Count: ${count()}, Doubled: ${doubled()}`)
-})
-
-count(5) // Logs: Count: 5, Doubled: 10
+effect(() => console.log(`${count()} × 2 = ${doubled()}`))
+count(5) // Logs: 5 × 2 = 10
 ```
 
-### Signal State
+## Proxy State
 
-Proxy-based reactive state that makes signals developer-friendly. Automatic dependency tracking with no manual redraw calls.
+Wraps signals in a proxy for ergonomic access. Components automatically track which properties they read and only re-render when those change.
 
 ```tsx
-import {state} from '@bitstillery/mithril'
-
-const $s = state(
-    {
-        count: 0,
-        user: {name: 'John'},
-        todos: [],
-        totalTodos: () => $s.todos.length, // Computed
-    },
-    'my.state',
-) // Name required for SSR serialization
-
-// Component only re-renders when $s.count changes
+import m, {state, MithrilComponent} from '@bitstillery/mithril'
+
+const $s = state({count: 0, todos: [], totalTodos: () => $s.todos.length}, 'app')
+
 class Counter extends MithrilComponent {
     view() {
         return (
             <div>
-                <p>Count: {$s.count}</p>
-                <button onclick={() => $s.count++}>Increment</button>
+                <p>{$s.count}</p>
+                <button onclick={() => $s.count++}>+</button>
             </div>
         )
     }
 }
-```
-
-### Persistent Store
 
-State persistence with automatic serialization. The `Store` class wraps `state()` with localStorage/sessionStorage support, seamlessly integrating with SSR hydration.
-
-```typescript
-import {Store} from '@bitstillery/mithril'
-
-const store = new Store<{user: {name: string}; preferences: Record<string, any>}>()
-
-// Define what persists vs what's volatile
-store.blueprint(
-    {user: {name: ''}, preferences: {}},
-    {
-        user: {name: ''}, // Persistent
-        preferences: {}, // Persistent
-    },
-)
-
-// Load from storage, or initialize with defaults
-store.load({user: {name: 'John'}, preferences: {theme: 'dark'}})
-
-// State is reactive and automatically saves on changes
-store.state.user.name = 'Jane' // Auto-saves to localStorage
+m.mount(document.body, Counter)
 ```
 
-### SSR Hydration
+The second argument to `state()` is a name used for SSR serialization.
 
-Server-side rendering with state preservation. `renderToString` automatically serializes state; restore it on the client before mounting.
+## SSR Hydration
 
 ```typescript
 // Server
@@ -94,57 +70,31 @@ const {html, state} = await m.renderToString(App)
 // Client
 import {deserializeAllStates} from '@bitstillery/mithril'
 
-const ssrState = document.getElementById('__SSR_STATE__')
-if (ssrState?.textContent) {
-    deserializeAllStates(JSON.parse(ssrState.textContent))
-}
+const el = document.getElementById('__SSR_STATE__')
+if (el?.textContent) deserializeAllStates(JSON.parse(el.textContent))
 m.mount(root, App)
 ```
 
-## The Complete Picture
-
-These features build on each other: signals provide the foundation for fine-grained reactivity, proxy-based state makes them developer-friendly, `Store` adds persistence for localStorage/sessionStorage, and SSR hydration enables search-engine friendly websites. The result? State that "just works"—from initial render through hydration, user interactions, and page refreshes—all while maintaining Mithril's familiar API.
-
-## Quick Start
-
-```bash
-bun add @bitstillery/mithril
-```
-
-```tsx
-import m, {state, MithrilComponent} from '@bitstillery/mithril'
+## Persistent Store
 
-const $s = state({count: 0}, 'app.state') // Name required for SSR
+`Store` wraps `state()` with localStorage/sessionStorage. Define a blueprint with defaults and which keys persist:
 
-class App extends MithrilComponent {
-    view() {
-        return (
-            <div>
-                <p>Count: {$s.count}</p>
-                <button onclick={() => $s.count++}>Increment</button>
-            </div>
-        )
-    }
-}
+```typescript
+import {Store} from '@bitstillery/mithril'
 
-m.mount(document.body, App)
+const store = new Store<{user: {name: string}; preferences: Record<string, any>}>()
+store.blueprint(
+    {user: {name: ''}, preferences: {}},
+    {user: {name: ''}, preferences: {}}, // Keys here persist to storage
+)
+store.load({user: {name: 'John'}, preferences: {theme: 'dark'}})
+store.state.user.name = 'Jane' // Auto-saves
 ```
 
 ## Examples
 
-- **SSR**: [`examples/ssr/`](examples/ssr/) - Server-side rendering with hydration
-- **State**: [`examples/state/`](examples/state/) - Signals, state management, and Store persistence patterns
-
-## Differences from Mithril.js
-
-| Feature          | Original            | This Fork                       |
-| ---------------- | ------------------- | ------------------------------- |
-| Reactivity       | Global `m.redraw()` | Fine-grained component updates  |
-| State Management | Manual redraw calls | Signals with automatic tracking |
-| SSR Hydration    | State loss          | Proper state preservation       |
-| TypeScript       | Community types     | Native TypeScript               |
-
-**100% API compatible** with Mithril.js v2.x. Signals are opt-in.
+- [`examples/ssr/`](examples/ssr/) — Server-side rendering with hydration
+- [`examples/state/`](examples/state/) — Signals, state, and Store patterns
 
 ## Development
 
@@ -155,31 +105,8 @@ bun test
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE).
 
 ## Credits
 
-Mithril.js was originally written by Leo Horie, but it is where it is today thanks to the hard work and great ideas of many people.
-
-Special thanks to:
-
-- Pat Cavit, who exposed most of the public API for Mithril.js 1.0, brought in test coverage and automated the publishing process
-- Claudia Meadows, who brought in linting, modernized the test suite and has been a strong voice in design discussions
-- Zoli Kahan, who replaced the original Promise implementation with one that actually worked properly
-- Alec Embke, who single-handedly wrote the JSON-P implementation
-- Barney Carroll, who suggested many great ideas and relentlessly pushed Mithril.js to the limit to uncover design issues prior to Mithril.js 1.0
-- Dominic Gannaway, who offered insanely meticulous technical insight into rendering performance
-- Boris Letocha, whose search space reduction algorithm is the basis for Mithril.js' virtual DOM engine
-- Joel Richard, whose monomorphic virtual DOM structure is the basis for Mithril.js' vnode implementation
-- Simon Friis Vindum, whose open source work was an inspiration to many design decisions for Mithril.js 1.0
-- Boris Kaul, for his awesome work on the benchmarking tools used to develop Mithril.js
-- Leon Sorokin, for writing a DOM instrumentation tool that helped improve performance in Mithril.js 1.0
-- Jordan Walke, whose work on React was prior art to the implementation of keys in Mithril.js
-- Pierre-Yves Gérardy, who consistently makes high quality contributions
-- Gyandeep Singh, who contributed significant IE performance improvements
-
-Other people who also deserve recognition:
-
-- Arthur Clemens - creator of [Polythene](https://github.com/ArthurClemens/Polythene) and the [HTML-to-Mithril converter](https://arthurclemens.github.io/mithril-template-converter/index.html)
-- Stephan Hoyer - creator of [mithril-node-render](https://github.com/StephanHoyer/mithril-node-render), [mithril-query](https://github.com/StephanHoyer/mithril-query) and [mithril-source-hint](https://github.com/StephanHoyer/mithril-source-hint)
-- the countless people who have reported and fixed bugs, participated in discussions, and helped promote Mithril.js
+Originally created by Leo Horie. See the [Mithril.js contributors](https://github.com/MithrilJS/mithril.js/graphs/contributors) for the many people who made Mithril what it is.

package/index.ts

@@ -1,3 +1,4 @@
+import './jsx.d.ts'
 import hyperscript from './render/hyperscript'
 import mountRedrawFactory from './api/mount-redraw'
 import routerFactory from './api/router'
@@ -8,7 +9,7 @@ import parsePathname from './pathname/parse'
 import buildPathname from './pathname/build'
 import VnodeFactory, {MithrilComponent} from './render/vnode'
 import censor from './util/censor'
-import next_tick from './util/next_tick'
+import nextTick from './util/next_tick'
 import domFor from './render/domFor'
 import {signal, computed, effect, Signal, ComputedSignal, setSignalRedrawCallback, getSignalComponents} from './signal'
 import {state, watch, registerState, getRegisteredStates, copyGlobalStatesToContext} from './state'
@@ -36,7 +37,7 @@ export interface MithrilStatic {
     buildPathname: (template: string, params: Record<string, any>) => string
     vnode: typeof VnodeFactory
     censor: (attrs: Record<string, any>, extras?: string[]) => Record<string, any>
-    next_tick: () => Promise<void>
+    nextTick: () => Promise<void>
     domFor: (vnode: Vnode) => Generator<Node, void, unknown>
 }
 
@@ -66,7 +67,7 @@ m.parsePathname = parsePathname
 m.buildPathname = buildPathname
 m.vnode = VnodeFactory
 m.censor = censor
-m.next_tick = next_tick
+m.nextTick = nextTick
 m.domFor = domFor
 
 // Set up signal-to-component redraw integration
@@ -82,7 +83,7 @@ setSignalRedrawCallback((sig: Signal<any>) => {
 
 // Export signals API
 export {signal, computed, effect, Signal, ComputedSignal, state, watch, registerState, getRegisteredStates}
-export type {State, StateOptions} from './state'
+export type {State, StateOptions, Unwatch} from './state'
 
 // Export Store class
 export {Store} from './store'
@@ -98,8 +99,8 @@ export type {SSRAccessContext} from './ssrContext'
 export {logger, Logger} from './server/logger'
 export type {LogContext} from './server/logger'
 
-// Export next_tick utility
-export {next_tick} from './util/next_tick'
+// Export nextTick utility
+export {nextTick} from './util/next_tick'
 
 // Export URI utilities
 export {getCurrentUrl, getPathname, getSearch, getHash, getLocation} from './util/uri'

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@bitstillery/mithril",
-    "version": "3.0.0-AA",
-    "description": "Mithril AA (AI Augmented) - Mithril + Signals, Store and SSR",
+    "version": "3.0.2",
+    "description": "Mithril + Signals, Store and SSR",
     "license": "MIT",
     "author": "Bitstillery",
     "repository": {
@@ -58,9 +58,19 @@
         "htm": "^3.1.1"
     },
     "devDependencies": {
+        "@codemirror/lang-html": "^6.4.9",
+        "@codemirror/lang-javascript": "^6.2.2",
+        "@codemirror/lang-json": "^6.0.2",
+        "@codemirror/state": "^6.4.1",
+        "@codemirror/theme-one-dark": "^6.1.2",
+        "@codemirror/view": "^6.39.1",
         "@types/bun": "^1.3.9",
         "@typescript/native-preview": "^7.0.0-dev.20260120.1",
+        "codemirror": "^6.0.1",
+        "marked": "^15.0.4",
+        "marked-gfm-heading-id": "^4.0.0",
         "oxfmt": "^0.32.0",
-        "oxlint": "^1.30.0"
+        "oxlint": "^1.30.0",
+        "tippy.js": "^6.3.7"
     }
 }

package/state.ts

@@ -990,13 +990,16 @@ export type State<T extends Record<string, any>> = {
     [K in keyof T]: T[K] extends (...args: any[]) => infer R ? R : T[K] extends Record<string, any> ? State<T[K]> : T[K]
 } & StateSignals<T>
 
+/** Function returned by watch() to remove the watcher */
+export type Unwatch = () => void
+
 /**
  * Watch a signal for changes
  * @param signal - The signal to watch
  * @param callback - Callback function called when signal value changes
  * @returns Unsubscribe function
  */
-export function watch<T>(signal: Signal<T> | ComputedSignal<T>, callback: (newValue: T, oldValue: T) => void): () => void {
+export function watch<T>(signal: Signal<T> | ComputedSignal<T>, callback: (newValue: T, oldValue: T) => void): Unwatch {
     const unwatch = signal.watch(callback)
 
     // Register watcher in SSR context for cleanup at end of request

package/util/next_tick.ts

@@ -1,5 +1,5 @@
 /**
- * Isomorphic next_tick utility
+ * Isomorphic nextTick utility
  *
  * Returns a Promise that resolves after the current execution stack completes.
  *
@@ -8,8 +8,7 @@
  *
  * @returns Promise that resolves on the next tick
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-async function next_tick(): Promise<void> {
+async function nextTick(): Promise<void> {
     // Check if we're in SSR mode
     if (typeof globalThis !== 'undefined' && (globalThis as any).__SSR_MODE__) {
         // In SSR mode, resolve immediately since SSR rendering is synchronous
@@ -41,5 +40,5 @@ async function next_tick(): Promise<void> {
     return Promise.resolve() as Promise<void>
 }
 
-export default next_tick
-export {next_tick}
+export default nextTick
+export {nextTick}