@brust/runtime-dom 2.0.0-alpha.4 → 2.0.0-alpha.6

package/README.md

@@ -95,3 +95,13 @@ tracking state lives on `globalThis[Symbol.for('brust.reactive.ctx')]`).
   React-free.
 - `@brust/runtime-dom/store/internal`: the server-resolver hook and serialization helpers the Bun worker uses.
   Not part of the public surface.
+
+## Feature modules (L33, F139)
+
+The runtime is a core plus feature modules, so a page loads only what its components use and the client JS does not grow as the compiler learns more of React.
+
+- `@brust/runtime-dom/core` (`src/core.ts`): signals, `defineBehavior`/`setChunkLoader`, `mount`/`unmount`, the binder registry (`BINDERS`) and the internals features need (`src/core-api.ts`). It knows no directive by name.
+- `@brust/runtime-dom/features/<name>` (`src/features/*.ts`): `basics` (`x-text`, `x-show`, `x-bind-*`, `x-on-*`, `x-ref`), `if`, `for`, `model`, `html`, `island` (React island hydration glue). A feature registers itself with the core when imported and imports the core only through `core-api`; in the browser build `core-api` is the shared core file, so there is one signal graph and one binder registry per page.
+- `@brust/runtime-dom` (`src/index.ts`) is core + every feature, for tests and non-split consumers. The browser build never uses it.
+
+**The rule for a new feature.** The micro-directives nearly every interactive page uses ship together in `basics`. Anything else gets its OWN module when it is at least about 1 KB gzip OR used by a minority of pages: `store`, `island`, `if`/`for`/`model`/`html` as measured, and every future feature (context, portal, focus trap, ...). Do not add a feature to `basics` or the core to save a file; add it as a module the compiler requests only for routes that use it. The CI byte budget (core + `basics`) holds the line.

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@brust/runtime-dom",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.6",
   "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./core": {
+      "types": "./src/core.ts",
+      "default": "./src/core.ts"
+    },
+    "./features/*": {
+      "types": "./src/features/*.ts",
+      "default": "./src/features/*.ts"
+    },
     "./store": {
       "types": "./src/store/index.ts",
       "default": "./src/store/index.ts"
@@ -49,5 +57,14 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "homepage": "https://brust.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetsArt/brust.git",
+    "directory": "packages/runtime-dom"
+  },
+  "bugs": {
+    "url": "https://github.com/AssetsArt/brust/issues"
   }
 }

package/src/core-api.ts

@@ -0,0 +1,10 @@
+// What a feature module may import from the core, and nothing else. In the browser build the core is one shared
+// ESM file and every feature is a separate file that imports these names from it (bundle.ts maps this module to the
+// core URL), so a feature registers on the page's single binder registry and signal graph.
+export { BINDERS, bindHost, bindElement, walkChildren } from './directives/index'
+export type { Binder } from './directives/index'
+export { parsed, read, member, mismatch, insideRaw, RAW_SEL } from './directives/common'
+export { hooks, islandHooks } from './instance'
+export { warnOnce } from './warn'
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
+export type { Signal, Computed, Dispose } from './signal'

package/src/core.ts

@@ -0,0 +1,8 @@
+// The always-loaded core: signals, the behavior registry, mount/unmount and the binder registry. Features
+// (./features/*) register their binders on import; nothing here knows a directive by name.
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
+export type { Signal, Computed, Dispose } from './signal'
+export { defineBehavior, setChunkLoader } from './registry'
+export type { BehaviorCtx, BehaviorFactory, BehaviorInstance } from './registry'
+export { mount, unmount } from './mount'
+export * from './core-api'

package/src/directives/bind.ts

@@ -1,6 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read } from './common'
-import { warnOnce } from '../warn'
+import { BINDERS, parsed, read, warnOnce } from '../core-api'
 
 // Attributes that execute or load code from a string; a bound value must never reach them as-is.
 const URL_ATTRS = new Set(['href', 'src', 'action', 'formaction', 'poster', 'data', 'xlink:href', 'ping'])

package/src/directives/for.ts

@@ -1,8 +1,4 @@
-import { BINDERS, bindElement, walkChildren } from './index'
-import { parsed, read, member } from './common'
-import { warnOnce } from '../warn'
-import { computed, signal, type Signal } from '../signal'
-import { hooks } from '../instance'
+import { BINDERS, bindElement, walkChildren, parsed, read, member, warnOnce, computed, signal, hooks, type Signal } from '../core-api'
 
 type RowScope = Record<string, unknown> & { __own: Signal<number> }
 

package/src/directives/html.ts

@@ -1,5 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read, mismatch } from './common'
+import { BINDERS, parsed, read, mismatch } from '../core-api'
 /** Both sides through the HTML parser (inert `<template>`), so `<br/>` vs `<br>` or entity spelling is not a mismatch. */
 function sameMarkup(el: Element, next: string): boolean {
   const t = document.createElement('template'); t.innerHTML = next

package/src/directives/if.ts

@@ -1,6 +1,4 @@
-import { BINDERS, bindElement, walkChildren } from './index'
-import { parsed, read } from './common'
-import { hooks } from '../instance'
+import { BINDERS, bindElement, walkChildren, parsed, read, hooks } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-if',
   bind: ({ inst, el, attr, raw, scope }) => {

package/src/directives/model.ts

@@ -1,7 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, member } from './common'
-import { isSignal, type Signal } from '../signal'
-import { warnOnce } from '../warn'
+import { BINDERS, parsed, member, isSignal, warnOnce, type Signal } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-model',
   bind: ({ inst, el, attr, raw }) => {

package/src/directives/on.ts

@@ -1,5 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, member } from './common'
+import { BINDERS, parsed, member } from '../core-api'
 BINDERS.push({
   match: (a) => a.startsWith('x-on-'),
   bind: ({ inst, el, attr, raw, scope }) => {

package/src/directives/ref.ts

@@ -1,4 +1,4 @@
-import { BINDERS } from './index'
+import { BINDERS } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-ref',
   bind: ({ inst, el, raw }) => {

package/src/directives/show.ts

@@ -1,5 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read } from './common'
+import { BINDERS, parsed, read } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-show',
   bind: ({ inst, el, attr, raw, scope }) => {

package/src/directives/text.ts

@@ -1,5 +1,4 @@
-import { BINDERS } from './index'
-import { parsed, read, mismatch } from './common'
+import { BINDERS, parsed, read, mismatch } from '../core-api'
 BINDERS.push({
   match: (a) => a === 'x-text',
   bind: ({ inst, el, attr, raw, scope }) => {

package/src/features/basics.ts

@@ -0,0 +1,6 @@
+// The directives nearly every interactive page uses, shipped as ONE module (see README "Feature modules").
+import '../directives/text'
+import '../directives/show'
+import '../directives/bind'
+import '../directives/on'
+import '../directives/ref'

package/src/features/for.ts

@@ -0,0 +1 @@
+import '../directives/for'

package/src/features/html.ts

@@ -0,0 +1 @@
+import '../directives/html'

package/src/features/if.ts

@@ -0,0 +1 @@
+import '../directives/if'

package/src/features/index.ts

@@ -0,0 +1,8 @@
+// Every feature at once: what `@brust/runtime-dom` (the full entry) loads. The browser build never uses this file;
+// it imports exactly the features a route needs.
+import './basics'
+import './if'
+import './for'
+import './model'
+import './html'
+import './island'

package/src/features/island.ts

@@ -0,0 +1,9 @@
+// React island hydration glue. Registers on the core's island hooks; hosts already in the document when this module
+// arrives (the core mounts first) are scheduled right away.
+import { islandHooks } from '../core-api'
+import { scheduleIslands, cancelIslands } from '../island'
+islandHooks.schedule = scheduleIslands
+islandHooks.cancel = cancelIslands
+if (typeof document !== 'undefined') scheduleIslands(document.documentElement)
+export { defineIsland } from '../island'
+export type { IslandHydrate } from '../island'

package/src/features/model.ts

@@ -0,0 +1 @@
+import '../directives/model'

package/src/features/store.ts

@@ -0,0 +1,6 @@
+// The store module: `defineStore` plus the reactive primitives a store's code imports (`@brust/core/store` aliases here),
+// re-exported from the core so there is one signal graph per page.
+export { signal, computed, effect, batch, untracked, isSignal, isComputed } from '../core-api'
+export type { Signal, Computed, Dispose } from '../core-api'
+export { defineStore } from '../store/define-store'
+export type { StoreHandle, Snapshot } from '../store/define-store'

package/src/index.ts

@@ -1,9 +1,8 @@
-export { signal, computed, effect, batch, untracked, isSignal, isComputed } from './signal'
-export type { Signal, Computed, Dispose } from './signal'
+// The full runtime: the core plus every feature. Tests and non-split consumers import this; the browser build
+// loads `./core` and only the `./features/*` a route needs.
+export * from './core'
 export { defineStore } from './store/define-store'
 export type { StoreHandle, Snapshot } from './store/define-store'
-export { defineBehavior, setChunkLoader } from './registry'
-export type { BehaviorCtx, BehaviorFactory, BehaviorInstance } from './registry'
-export { mount, unmount } from './mount'
 export { defineIsland } from './island'
 export type { IslandHydrate } from './island'
+import './features/index'

package/src/instance.ts

@@ -93,3 +93,6 @@ export function nearestInstance(el: Element): Instance | null {
 
 /** Late-bound by mount.ts so binders (x-if, x-for) can mount nested hosts synchronously without an import cycle. */
 export const hooks: { mountTree: (root: ParentNode) => void } = { mountTree: () => {} }
+
+/** Late-bound by the `island` feature (features/island.ts) so a page without React islands never loads the hydration glue. */
+export const islandHooks: { schedule: (root: ParentNode) => void; cancel: (root: Node) => void } = { schedule: () => {}, cancel: () => {} }

package/src/island.ts

@@ -1,8 +1,7 @@
 // React islands: the server paints <brust-island data-id x-props>HTML</brust-island>; the island's
 // chunk registers a hydrate function through a global queue (no import of the runtime); the runtime
 // hydrates each host once, when idle (spec S12). Load order between runtime and chunks is free.
-import { warnOnce } from './warn'
-import { insideRaw } from './directives/common'
+import { warnOnce, insideRaw } from './core-api'
 
 export type IslandHydrate = (host: HTMLElement, props: Record<string, unknown>) => void
 type QueueEntry = [string, IslandHydrate]

package/src/mount.ts

@@ -1,12 +1,10 @@
-import { Instance, hooks, instances, nearestInstance } from './instance'
+import { Instance, hooks, instances, islandHooks, nearestInstance } from './instance'
 import { untracked } from './signal'
 import { whenBehavior } from './registry'
 import { bindHost } from './directives/index'
 import { insideRaw } from './directives/common'
 import { warnOnce } from './warn'
 import { bindPropsFromParent } from './props-bind'
-import { scheduleIslands, cancelIslands } from './island'
-import './directives/register'   // Tasks 3–6 add binders here (file created in Task 3; create it empty now)
 
 let observer: MutationObserver | null = null
 
@@ -44,13 +42,13 @@ function mountTree(root: ParentNode): void {
   root.querySelectorAll<HTMLElement>('[x-data]').forEach((h) => hosts.push(h))
   // document order = parents before children, so nearestInstance finds a mounted parent
   for (const h of hosts) if (!insideRaw(h)) mountHost(h)
-  scheduleIslands(root)
+  islandHooks.schedule(root)
 }
 hooks.mountTree = (root) => untracked(() => mountTree(root))
 
 function disposeTree(root: Node): void {
   if (!(root instanceof Element)) return
-  cancelIslands(root)
+  islandHooks.cancel(root)
   const hosts: Element[] = root.hasAttribute('x-data') ? [root] : []
   root.querySelectorAll('[x-data]').forEach((h) => hosts.push(h))
   for (const h of hosts) { const i = instances.get(h); if (i) { i.dispose(); instances.delete(h) } }

package/src/store/define-store.ts

@@ -1,6 +1,6 @@
 // defineStore (M3-F D1): the 0.1.x `brustjs/store` handle on the shared reactive core and the
 // globalThis registry. Resolution (browser registry / server resolver) lives in ./registry.
-import { type Computed, type Signal, isSignal } from '../signal'
+import { type Computed, type Signal, isSignal } from '../core-api'
 import { type StoreInstanceRecord, computeSnapshot, resolveRecord } from './registry'
 
 // Unwrap a Signal/Computed to its value type; `never` if it is neither. Uses `infer` (not

package/src/store/registry.ts

@@ -1,6 +1,6 @@
 // Browser store registry + the server-resolver hook (M3-F D3/D6/C7).
 // The registry lives on globalThis (C7) so two copies of this module share one instance per name.
-import { isComputed, isSignal, untracked } from '../signal'
+import { isComputed, isSignal, untracked } from '../core-api'
 import { parseStoreScript } from './serialize'
 
 // The resolved per-scope store record, shared by the browser registry and the server per-request

package/src/directives/register.ts

@@ -1,9 +0,0 @@
-import './text'
-import './html'
-import './show'
-import './bind'
-import './on'
-import './if'
-import './model'
-import './for'
-import './ref'