@ipxjs/refract 0.3.1

package/src/refract/fiber.ts

@@ -0,0 +1,10 @@
+export {
+  currentFiber,
+  pushDeletion,
+  renderFiber,
+  scheduleRender,
+} from "./coreRenderer.js";
+export { markPendingEffects } from "./hooksRuntime.js";
+export { memo, shallowEqual } from "./memo.js";
+export { setHtmlSanitizer } from "./features/security.js";
+export type { HtmlSanitizer } from "./dom.js";

package/src/refract/full.ts

@@ -0,0 +1,14 @@
+export { createElement, Fragment } from "./createElement.js";
+export { render } from "./render.js";
+export { memo } from "./memo.js";
+export { setHtmlSanitizer } from "./features/security.js";
+export { setDevtoolsHook, DEVTOOLS_GLOBAL_HOOK } from "./devtools.js";
+export { useState, useEffect, useRef, useMemo, useCallback, useReducer, createRef, useErrorBoundary } from "./features/hooks.js";
+export { createContext, useContext } from "./features/context.js";
+export type { VNode, Props, Component } from "./types.js";
+export type {
+  RefractDevtoolsHook,
+  RefractDevtoolsFiberSnapshot,
+  RefractDevtoolsRootSnapshot,
+  RefractDevtoolsRenderer,
+} from "./devtools.js";

package/src/refract/hooks.ts

@@ -0,0 +1,11 @@
+export {
+  useState,
+  useEffect,
+  useRef,
+  useMemo,
+  useCallback,
+  useReducer,
+  createRef,
+  useErrorBoundary,
+  depsChanged,
+} from "./features/hooks.js";

package/src/refract/hooksRuntime.ts

@@ -0,0 +1,63 @@
+import type { Fiber } from "./types.js";
+import { reconcileChildren } from "./reconcile.js";
+import {
+  registerAfterCommitHandler,
+  registerFiberCleanupHandler,
+  registerRenderErrorHandler,
+} from "./runtimeExtensions.js";
+
+const fibersWithPendingEffects = new Set<Fiber>();
+
+export function markPendingEffects(fiber: Fiber): void {
+  fibersWithPendingEffects.add(fiber);
+}
+
+function cleanupFiberEffects(fiber: Fiber): void {
+  fibersWithPendingEffects.delete(fiber);
+  if (!fiber.hooks) return;
+
+  for (const hook of fiber.hooks) {
+    const state = hook.state as { cleanup?: () => void } | undefined;
+    if (state?.cleanup) {
+      state.cleanup();
+      state.cleanup = undefined;
+    }
+  }
+}
+
+function runPendingEffects(): void {
+  for (const fiber of fibersWithPendingEffects) {
+    if (!fiber.hooks) continue;
+
+    for (const hook of fiber.hooks) {
+      const state = hook.state as {
+        effect?: () => void | (() => void);
+        pending?: boolean;
+        cleanup?: () => void;
+      } | undefined;
+      if (state?.pending && state.effect) {
+        if (state.cleanup) state.cleanup();
+        state.cleanup = state.effect() || undefined;
+        state.pending = false;
+      }
+    }
+  }
+  fibersWithPendingEffects.clear();
+}
+
+function handleErrorBoundary(fiber: Fiber, error: unknown): boolean {
+  let current: Fiber | null = fiber.parent;
+  while (current) {
+    if (current._errorHandler) {
+      current._errorHandler(error);
+      reconcileChildren(fiber, []);
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+registerFiberCleanupHandler(cleanupFiberEffects);
+registerAfterCommitHandler(runPendingEffects);
+registerRenderErrorHandler(handleErrorBoundary);

package/src/refract/index.ts

@@ -0,0 +1 @@
+export * from "./full.js";

package/src/refract/memo.ts

@@ -0,0 +1,27 @@
+import type { Props, VNode } from "./types.js";
+import { MEMO_MARKER, type MemoComponent } from "./memoMarker.js";
+import { ensureMemoRuntime } from "./features/memoRuntime.js";
+
+/** Shallow equality comparison for memo */
+export function shallowEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (key === "children") continue;
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+export function memo(
+  component: (props: Props) => VNode,
+  compare?: (a: Record<string, unknown>, b: Record<string, unknown>) => boolean,
+): (props: Props) => VNode {
+  ensureMemoRuntime();
+  const memoComp: MemoComponent = ((props: Props) => component(props)) as MemoComponent;
+  memoComp._inner = component;
+  memoComp._compare = compare ?? shallowEqual;
+  memoComp._memo = MEMO_MARKER;
+  return memoComp;
+}

package/src/refract/memoMarker.ts

@@ -0,0 +1,14 @@
+import type { Props, VNode } from "./types.js";
+
+export const MEMO_MARKER = Symbol.for("refract.memo");
+
+export interface MemoComponent {
+  (props: Props): VNode;
+  _inner: (props: Props) => VNode;
+  _compare: (a: Record<string, unknown>, b: Record<string, unknown>) => boolean;
+  _memo: typeof MEMO_MARKER;
+}
+
+export function isMemoComponent(type: unknown): type is MemoComponent {
+  return typeof type === "function" && (type as MemoComponent)._memo === MEMO_MARKER;
+}

package/src/refract/reconcile.ts

@@ -0,0 +1,185 @@
+import type { VNode, Fiber } from "./types.js";
+import { PLACEMENT, UPDATE, DELETION } from "./types.js";
+import { pushDeletion } from "./coreRenderer.js";
+
+function createDeletionScheduler(): (fiber: Fiber) => void {
+  const scheduled = new Set<Fiber>();
+  return (fiber: Fiber) => {
+    if (scheduled.has(fiber)) return;
+    scheduled.add(fiber);
+    fiber.flags = DELETION;
+    pushDeletion(fiber);
+  };
+}
+
+function createFiber(
+  child: VNode,
+  parentFiber: Fiber,
+  oldFiber: Fiber | null,
+): Fiber {
+  if (oldFiber && oldFiber.type === child.type) {
+    return {
+      type: oldFiber.type,
+      props: child.props,
+      key: child.key,
+      dom: oldFiber.dom,
+      parentDom: parentFiber.dom ?? parentFiber.parentDom,
+      parent: parentFiber,
+      child: null,
+      sibling: null,
+      hooks: oldFiber.hooks,
+      alternate: oldFiber,
+      flags: UPDATE,
+    };
+  }
+  return {
+    type: child.type,
+    props: child.props,
+    key: child.key,
+    dom: null,
+    parentDom: parentFiber.dom ?? parentFiber.parentDom,
+    parent: parentFiber,
+    child: null,
+    sibling: null,
+    hooks: null,
+    alternate: null,
+    flags: PLACEMENT,
+  };
+}
+
+/** Reconcile a fiber's children against a new list of VNodes */
+export function reconcileChildren(parentFiber: Fiber, children: VNode[]): void {
+  const oldChildren = collectOldChildren(parentFiber);
+  const hasKeys = children.some((c) => c.key != null);
+
+  if (hasKeys) {
+    reconcileKeyed(parentFiber, children, oldChildren);
+  } else {
+    reconcilePositional(parentFiber, children, oldChildren);
+  }
+}
+
+function collectOldChildren(parentFiber: Fiber): Fiber[] {
+  const result: Fiber[] = [];
+  let f = parentFiber.alternate?.child ?? null;
+  while (f) {
+    result.push(f);
+    f = f.sibling;
+  }
+  return result;
+}
+
+function reconcilePositional(
+  parentFiber: Fiber,
+  children: VNode[],
+  oldChildren: Fiber[],
+): void {
+  const scheduleDeletion = createDeletionScheduler();
+  let prevSibling: Fiber | null = null;
+  const maxLen = Math.max(children.length, oldChildren.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const child = i < children.length ? children[i] : null;
+    const oldFiber = i < oldChildren.length ? oldChildren[i] : null;
+
+    let newFiber: Fiber | null = null;
+
+    if (child) {
+      newFiber = createFiber(child, parentFiber, oldFiber);
+    }
+
+    if (oldFiber && (!child || oldFiber.type !== child.type)) {
+      scheduleDeletion(oldFiber);
+    }
+
+    if (i === 0) {
+      parentFiber.child = newFiber;
+    } else if (prevSibling && newFiber) {
+      prevSibling.sibling = newFiber;
+    }
+
+    if (newFiber) prevSibling = newFiber;
+  }
+}
+
+function reconcileKeyed(
+  parentFiber: Fiber,
+  children: VNode[],
+  oldChildren: Fiber[],
+): void {
+  const scheduleDeletion = createDeletionScheduler();
+  // Build map of keyed old fibers
+  const keyMap = new Map<string | number, Fiber>();
+  const unkeyedOld: Fiber[] = [];
+  const oldIndexMap = new Map<Fiber, number>();
+  for (const f of oldChildren) {
+    oldIndexMap.set(f, oldIndexMap.size);
+    if (f.key != null) {
+      keyMap.set(f.key, f);
+    } else {
+      unkeyedOld.push(f);
+    }
+  }
+
+  let prevSibling: Fiber | null = null;
+  let unkeyedIndex = 0;
+  let lastPlacedIndex = 0;
+  const usedOld = new Set<Fiber>();
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    let oldFiber: Fiber | null = null;
+
+    if (child.key != null) {
+      oldFiber = keyMap.get(child.key) ?? null;
+    } else {
+      // Match unkeyed by position
+      while (unkeyedIndex < unkeyedOld.length) {
+        const candidate = unkeyedOld[unkeyedIndex];
+        unkeyedIndex++;
+        if (candidate.type === child.type) {
+          oldFiber = candidate;
+          break;
+        } else {
+          scheduleDeletion(candidate);
+        }
+      }
+    }
+
+    const newFiber = createFiber(child, parentFiber, oldFiber);
+
+    if (oldFiber) {
+      usedOld.add(oldFiber);
+      // Check if we need to move
+      const oldIndex = oldIndexMap.get(oldFiber)!;
+      if (oldIndex < lastPlacedIndex) {
+        newFiber.flags = PLACEMENT;
+      } else {
+        lastPlacedIndex = oldIndex;
+      }
+    }
+
+    if (i === 0) {
+      parentFiber.child = newFiber;
+    } else if (prevSibling) {
+      prevSibling.sibling = newFiber;
+    }
+
+    prevSibling = newFiber;
+  }
+
+  // Delete remaining old fibers that weren't matched
+  for (const f of oldChildren) {
+    if (!usedOld.has(f)) {
+      scheduleDeletion(f);
+    }
+  }
+
+  // Delete remaining unkeyed old fibers
+  while (unkeyedIndex < unkeyedOld.length) {
+    const f = unkeyedOld[unkeyedIndex++];
+    if (!usedOld.has(f)) {
+      scheduleDeletion(f);
+    }
+  }
+}

package/src/refract/render.ts

@@ -0,0 +1,9 @@
+import type { VNode } from "./types.js";
+import { renderFiber } from "./coreRenderer.js";
+import { ensureSecurityDefaults } from "./features/security.js";
+
+/** Renders a VNode tree into a DOM container with security defaults */
+export function render(vnode: VNode, container: HTMLElement): void {
+  ensureSecurityDefaults();
+  renderFiber(vnode, container);
+}

package/src/refract/renderCore.ts

@@ -0,0 +1,7 @@
+import type { VNode } from "./types.js";
+import { renderFiber } from "./coreRenderer.js";
+
+/** Renders a VNode tree into a DOM container */
+export function render(vnode: VNode, container: HTMLElement): void {
+  renderFiber(vnode, container);
+}

package/src/refract/runtimeExtensions.ts

@@ -0,0 +1,80 @@
+import type { Fiber } from "./types.js";
+
+type FiberCleanupHandler = (fiber: Fiber) => void;
+type AfterCommitHandler = () => void;
+type RenderErrorHandler = (fiber: Fiber, error: unknown) => boolean;
+type CommitHandler = (rootFiber: Fiber, deletions: Fiber[]) => void;
+type ComponentBailoutHandler = (fiber: Fiber) => boolean;
+
+const fiberCleanupHandlers = new Set<FiberCleanupHandler>();
+const afterCommitHandlers = new Set<AfterCommitHandler>();
+const renderErrorHandlers = new Set<RenderErrorHandler>();
+const commitHandlers = new Set<CommitHandler>();
+const componentBailoutHandlers = new Set<ComponentBailoutHandler>();
+
+function makeUnregister<T>(set: Set<T>, value: T): () => void {
+  return () => {
+    set.delete(value);
+  };
+}
+
+export function registerFiberCleanupHandler(handler: FiberCleanupHandler): () => void {
+  fiberCleanupHandlers.add(handler);
+  return makeUnregister(fiberCleanupHandlers, handler);
+}
+
+export function registerAfterCommitHandler(handler: AfterCommitHandler): () => void {
+  afterCommitHandlers.add(handler);
+  return makeUnregister(afterCommitHandlers, handler);
+}
+
+export function registerRenderErrorHandler(handler: RenderErrorHandler): () => void {
+  renderErrorHandlers.add(handler);
+  return makeUnregister(renderErrorHandlers, handler);
+}
+
+export function registerCommitHandler(handler: CommitHandler): () => void {
+  commitHandlers.add(handler);
+  return makeUnregister(commitHandlers, handler);
+}
+
+export function registerComponentBailoutHandler(handler: ComponentBailoutHandler): () => void {
+  componentBailoutHandlers.add(handler);
+  return makeUnregister(componentBailoutHandlers, handler);
+}
+
+export function runFiberCleanupHandlers(fiber: Fiber): void {
+  for (const handler of fiberCleanupHandlers) {
+    handler(fiber);
+  }
+}
+
+export function runAfterCommitHandlers(): void {
+  for (const handler of afterCommitHandlers) {
+    handler();
+  }
+}
+
+export function tryHandleRenderError(fiber: Fiber, error: unknown): boolean {
+  for (const handler of renderErrorHandlers) {
+    if (handler(fiber, error)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function runCommitHandlers(rootFiber: Fiber, deletions: Fiber[]): void {
+  for (const handler of commitHandlers) {
+    handler(rootFiber, deletions);
+  }
+}
+
+export function shouldBailoutComponent(fiber: Fiber): boolean {
+  for (const handler of componentBailoutHandlers) {
+    if (handler(fiber)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/refract/types.ts

@@ -0,0 +1,48 @@
+/** A functional component */
+export type Component = (props: Props) => VNode;
+
+/** The `type` field of a VNode — any HTML tag string, fragment symbol, or component */
+export type VNodeType = string | symbol | Component;
+
+/** Props passed to elements and components */
+export interface Props {
+  [key: string]: unknown;
+  children?: VNode[];
+  key?: string | number;
+}
+
+/** A virtual DOM node */
+export interface VNode {
+  type: VNodeType | "TEXT";
+  props: Props;
+  key: string | number | null;
+}
+
+/** Fiber flags for commit phase */
+export const PLACEMENT = 1;
+export const UPDATE = 2;
+export const DELETION = 4;
+
+/** A hook state slot */
+export interface Hook {
+  state: unknown;
+  queue?: unknown[];
+}
+
+/** Internal fiber node — represents a mounted VNode */
+export interface Fiber {
+  type: VNodeType | "TEXT";
+  props: Props;
+  key: string | number | null;
+  dom: Node | null;
+  parentDom: Node;
+  parent: Fiber | null;
+  child: Fiber | null;
+  sibling: Fiber | null;
+  hooks: Hook[] | null;
+  _hookIndex?: number;
+  _contexts?: Map<number, unknown>;
+  _errorHandler?: (error: unknown) => void;
+  alternate: Fiber | null;
+  flags: number;
+}

package/tests/context.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createElement } from "../src/refract/createElement.js";
+import { render } from "../src/refract/render.js";
+import { createContext, useContext } from "../src/refract/context.js";
+
+describe("context", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+  });
+
+  it("provides default value when no Provider", () => {
+    const ThemeCtx = createContext("light");
+    function App() {
+      const theme = useContext(ThemeCtx);
+      return createElement("span", null, theme);
+    }
+    render(createElement(App, null), container);
+    expect(container.querySelector("span")!.textContent).toBe("light");
+  });
+
+  it("provides value from Provider", () => {
+    const ThemeCtx = createContext("light");
+    function Child() {
+      const theme = useContext(ThemeCtx);
+      return createElement("span", null, theme);
+    }
+    function App() {
+      return createElement(ThemeCtx.Provider, { value: "dark" },
+        createElement(Child, null),
+      );
+    }
+    render(createElement(App, null), container);
+    expect(container.querySelector("span")!.textContent).toBe("dark");
+  });
+
+  it("uses nearest Provider value with nested providers", () => {
+    const ThemeCtx = createContext("default");
+    function Child() {
+      const theme = useContext(ThemeCtx);
+      return createElement("span", null, theme);
+    }
+    function App() {
+      return createElement(ThemeCtx.Provider, { value: "outer" },
+        createElement(ThemeCtx.Provider, { value: "inner" },
+          createElement(Child, null),
+        ),
+      );
+    }
+    render(createElement(App, null), container);
+    expect(container.querySelector("span")!.textContent).toBe("inner");
+  });
+
+  it("supports multiple contexts", () => {
+    const ThemeCtx = createContext("light");
+    const LangCtx = createContext("en");
+    function Child() {
+      const theme = useContext(ThemeCtx);
+      const lang = useContext(LangCtx);
+      return createElement("span", null, `${theme}-${lang}`);
+    }
+    function App() {
+      return createElement(ThemeCtx.Provider, { value: "dark" },
+        createElement(LangCtx.Provider, { value: "fr" },
+          createElement(Child, null),
+        ),
+      );
+    }
+    render(createElement(App, null), container);
+    expect(container.querySelector("span")!.textContent).toBe("dark-fr");
+  });
+
+  it("does not add an extra DOM wrapper for provider children", () => {
+    const ThemeCtx = createContext("light");
+    function App() {
+      return createElement("div", null,
+        createElement(ThemeCtx.Provider, { value: "dark" },
+          createElement("span", null, "one"),
+          createElement("span", null, "two"),
+        ),
+      );
+    }
+    render(createElement(App, null), container);
+    const div = container.querySelector("div")!;
+    expect(div.children).toHaveLength(2);
+    expect(div.children[0].textContent).toBe("one");
+    expect(div.children[1].textContent).toBe("two");
+  });
+});

package/tests/createElement.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { createElement } from "../src/refract/createElement.js";
+
+describe("createElement", () => {
+  it("creates a simple element with no children", () => {
+    const vnode = createElement("img", { src: "cat.jpg", alt: "A cat" });
+    expect(vnode.type).toBe("img");
+    expect(vnode.props.src).toBe("cat.jpg");
+    expect(vnode.props.alt).toBe("A cat");
+    expect(vnode.props.children).toBeUndefined();
+    expect(vnode.key).toBeNull();
+  });
+
+  it("creates an element with string children as text nodes", () => {
+    const vnode = createElement("span", null, "hello");
+    expect(vnode.props.children).toHaveLength(1);
+    expect(vnode.props.children![0].type).toBe("TEXT");
+    expect(vnode.props.children![0].props.nodeValue).toBe("hello");
+  });
+
+  it("creates nested elements", () => {
+    const vnode = createElement(
+      "div",
+      { className: "card" },
+      createElement("img", { src: "pic.jpg" }),
+      createElement("span", null, "Caption"),
+    );
+    expect(vnode.type).toBe("div");
+    expect(vnode.props.children).toHaveLength(2);
+    expect(vnode.props.children![0].type).toBe("img");
+    expect(vnode.props.children![1].type).toBe("span");
+  });
+
+  it("flattens array children", () => {
+    const items = ["a", "b", "c"];
+    const vnode = createElement(
+      "div",
+      null,
+      items.map((t) => createElement("span", null, t)),
+    );
+    expect(vnode.props.children).toHaveLength(3);
+  });
+
+  it("filters out null, undefined, and boolean children", () => {
+    const vnode = createElement("div", null, null, undefined, false, true, "text");
+    expect(vnode.props.children).toHaveLength(1);
+    expect(vnode.props.children![0].type).toBe("TEXT");
+  });
+
+  it("retains function type for components (deferred)", () => {
+    const MyImg = (props: Record<string, unknown>) =>
+      createElement("img", { src: props.src as string });
+
+    const vnode = createElement(MyImg, { src: "photo.jpg" });
+    // Components are NOT called eagerly — type stays as the function
+    expect(vnode.type).toBe(MyImg);
+    expect(vnode.props.src).toBe("photo.jpg");
+  });
+
+  it("converts numbers to text nodes", () => {
+    const vnode = createElement("span", null, 42);
+    expect(vnode.props.children).toHaveLength(1);
+    expect(vnode.props.children![0].props.nodeValue).toBe("42");
+  });
+
+  it("extracts key from props", () => {
+    const vnode = createElement("div", { key: "abc", className: "x" });
+    expect(vnode.key).toBe("abc");
+    expect(vnode.props.key).toBeUndefined();
+  });
+});