@ipxjs/refract 0.3.1

package/src/refract/createElement.ts

@@ -0,0 +1,40 @@
+import type { VNode, VNodeType, Props } from "./types.js";
+
+export const Fragment = Symbol.for("refract.fragment");
+
+type Child = VNode | string | number | boolean | null | undefined | Child[];
+
+export function createElement(
+  type: VNodeType,
+  props: Record<string, unknown> | null,
+  ...rawChildren: Child[]
+): VNode {
+  const resolvedProps: Props = { ...(props ?? {}) };
+
+  // Extract key from props
+  const key = resolvedProps.key ?? null;
+  delete resolvedProps.key;
+
+  const children = flattenChildren(rawChildren);
+  if (children.length > 0) {
+    resolvedProps.children = children;
+  }
+
+  // Do NOT call component functions — they are called during reconciliation
+  return { type, props: resolvedProps, key };
+}
+
+function flattenChildren(raw: Child[]): VNode[] {
+  const result: VNode[] = [];
+  for (const child of raw) {
+    if (child == null || typeof child === "boolean") continue;
+    if (Array.isArray(child)) {
+      result.push(...flattenChildren(child));
+    } else if (typeof child === "string" || typeof child === "number") {
+      result.push({ type: "TEXT", props: { nodeValue: String(child) }, key: null });
+    } else {
+      result.push(child);
+    }
+  }
+  return result;
+}

package/src/refract/devtools.ts

@@ -0,0 +1,254 @@
+import type { Fiber, Props } from "./types.js";
+import { registerCommitHandler } from "./runtimeExtensions.js";
+
+export const DEVTOOLS_GLOBAL_HOOK = "__REFRACT_DEVTOOLS_GLOBAL_HOOK__";
+
+export interface RefractDevtoolsRenderer {
+  name: "refract";
+}
+
+export interface RefractDevtoolsFiberSnapshot {
+  id: number;
+  type: string;
+  key: string | number | null;
+  dom: string | null;
+  props: Record<string, unknown>;
+  hookState: unknown[];
+  children: RefractDevtoolsFiberSnapshot[];
+}
+
+export interface RefractDevtoolsRootSnapshot {
+  id: number;
+  container: string;
+  current: RefractDevtoolsFiberSnapshot | null;
+}
+
+export interface RefractDevtoolsHook {
+  inject?: (renderer: RefractDevtoolsRenderer) => number;
+  onCommitFiberRoot?: (rendererId: number, root: RefractDevtoolsRootSnapshot) => void;
+  onCommitFiberUnmount?: (rendererId: number, fiber: RefractDevtoolsFiberSnapshot) => void;
+}
+
+let explicitHook: RefractDevtoolsHook | null | undefined = undefined;
+let activeHook: RefractDevtoolsHook | null = null;
+let activeRendererId = 1;
+
+const containerIds = new WeakMap<Node, number>();
+let nextContainerId = 1;
+
+const fiberIds = new WeakMap<Fiber, number>();
+let nextFiberId = 1;
+
+export function setDevtoolsHook(hook?: RefractDevtoolsHook | null): void {
+  explicitHook = hook;
+  activeHook = null;
+  activeRendererId = 1;
+}
+
+export function reportDevtoolsCommit(rootFiber: Fiber, deletions: Fiber[]): void {
+  const hook = resolveHook();
+  if (!hook) {
+    activeHook = null;
+    activeRendererId = 1;
+    return;
+  }
+
+  const rendererId = ensureRenderer(hook);
+
+  if (typeof hook.onCommitFiberRoot === "function") {
+    safeCall(() => hook.onCommitFiberRoot!(rendererId, snapshotRoot(rootFiber)));
+  }
+
+  if (typeof hook.onCommitFiberUnmount === "function") {
+    for (const deleted of deletions) {
+      walkFiberSubtree(deleted, (fiber) => {
+        safeCall(() => hook.onCommitFiberUnmount!(rendererId, snapshotFiber(fiber)));
+      });
+    }
+  }
+}
+
+registerCommitHandler(reportDevtoolsCommit);
+
+function resolveHook(): RefractDevtoolsHook | null {
+  if (explicitHook !== undefined) return explicitHook;
+
+  const candidate = (globalThis as Record<string, unknown>)[DEVTOOLS_GLOBAL_HOOK];
+  if (!candidate || typeof candidate !== "object") return null;
+  return candidate as RefractDevtoolsHook;
+}
+
+function ensureRenderer(hook: RefractDevtoolsHook): number {
+  if (hook === activeHook) return activeRendererId;
+
+  activeHook = hook;
+  activeRendererId = 1;
+
+  if (typeof hook.inject === "function") {
+    safeCall(() => {
+      const id = hook.inject!({ name: "refract" });
+      if (typeof id === "number" && Number.isFinite(id)) {
+        activeRendererId = id;
+      }
+    });
+  }
+
+  return activeRendererId;
+}
+
+function snapshotRoot(rootFiber: Fiber): RefractDevtoolsRootSnapshot {
+  const containerNode = rootFiber.dom ?? rootFiber.parentDom;
+  return {
+    id: getContainerId(containerNode),
+    container: describeNode(containerNode) ?? "unknown",
+    current: rootFiber.child ? snapshotFiber(rootFiber.child) : null,
+  };
+}
+
+function snapshotFiber(fiber: Fiber): RefractDevtoolsFiberSnapshot {
+  const children: RefractDevtoolsFiberSnapshot[] = [];
+  let child = fiber.child;
+  while (child) {
+    children.push(snapshotFiber(child));
+    child = child.sibling;
+  }
+
+  return {
+    id: getFiberId(fiber),
+    type: describeFiberType(fiber),
+    key: fiber.key,
+    dom: describeNode(fiber.dom),
+    props: snapshotProps(fiber.props),
+    hookState: snapshotHookState(fiber),
+    children,
+  };
+}
+
+function snapshotHookState(fiber: Fiber): unknown[] {
+  if (!fiber.hooks || fiber.hooks.length === 0) return [];
+  return fiber.hooks.map((hook) => serializeValue(hook.state, new WeakSet<object>(), 0));
+}
+
+function snapshotProps(props: Props): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const keys = Object.keys(props).filter((key) => key !== "children");
+
+  for (const key of keys.slice(0, 20)) {
+    out[key] = serializeValue(props[key], new WeakSet<object>(), 0);
+  }
+  if (keys.length > 20) {
+    out.__truncated = `${keys.length - 20} more keys`;
+  }
+  return out;
+}
+
+function serializeValue(value: unknown, seen: WeakSet<object>, depth: number): unknown {
+  if (value == null) return value;
+
+  switch (typeof value) {
+    case "string":
+    case "number":
+    case "boolean":
+      return value;
+    case "bigint":
+    case "symbol":
+      return String(value);
+    case "function": {
+      const name = value.name || "anonymous";
+      return `[function ${name}]`;
+    }
+    case "object": {
+      if (typeof Node !== "undefined" && value instanceof Node) {
+        return `[node ${describeNode(value) ?? value.nodeName.toLowerCase()}]`;
+      }
+      if (depth >= 2) {
+        return Array.isArray(value) ? "[array]" : "[object]";
+      }
+      if (value instanceof Date) return value.toISOString();
+      if (value instanceof RegExp) return String(value);
+
+      if (seen.has(value)) return "[circular]";
+      seen.add(value);
+
+      if (Array.isArray(value)) {
+        const items = value.slice(0, 10).map((item) => serializeValue(item, seen, depth + 1));
+        if (value.length > 10) {
+          items.push(`[+${value.length - 10} more items]`);
+        }
+        return items;
+      }
+
+      const record = value as Record<string, unknown>;
+      const entries = Object.entries(record);
+      const out: Record<string, unknown> = {};
+      for (const [key, entryValue] of entries.slice(0, 10)) {
+        out[key] = serializeValue(entryValue, seen, depth + 1);
+      }
+      if (entries.length > 10) {
+        out.__truncated = `${entries.length - 10} more keys`;
+      }
+      return out;
+    }
+    default:
+      return String(value);
+  }
+}
+
+function describeFiberType(fiber: Fiber): string {
+  if (fiber.type === "TEXT") return "#text";
+  if (typeof fiber.type === "string") return fiber.type;
+  if (typeof fiber.type === "symbol") return fiber.type.description ?? "Symbol";
+  if (typeof fiber.type === "function") return fiber.type.name || "Anonymous";
+  return "Unknown";
+}
+
+function describeNode(node: Node | null): string | null {
+  if (!node) return null;
+
+  if (typeof Element !== "undefined" && node instanceof Element) {
+    const tag = node.tagName.toLowerCase();
+    return node.id ? `${tag}#${node.id}` : tag;
+  }
+  if (node.nodeType === Node.TEXT_NODE) return "#text";
+  return node.nodeName.toLowerCase();
+}
+
+function getContainerId(container: Node): number {
+  const existing = containerIds.get(container);
+  if (existing !== undefined) return existing;
+  const id = nextContainerId++;
+  containerIds.set(container, id);
+  return id;
+}
+
+function getFiberId(fiber: Fiber): number {
+  const existing = fiberIds.get(fiber);
+  if (existing !== undefined) return existing;
+
+  const alternateId = fiber.alternate ? fiberIds.get(fiber.alternate) : undefined;
+  if (alternateId !== undefined) {
+    fiberIds.set(fiber, alternateId);
+    return alternateId;
+  }
+
+  const id = nextFiberId++;
+  fiberIds.set(fiber, id);
+  return id;
+}
+
+function walkFiberSubtree(fiber: Fiber, visit: (f: Fiber) => void): void {
+  visit(fiber);
+  let child = fiber.child;
+  while (child) {
+    walkFiberSubtree(child, visit);
+    child = child.sibling;
+  }
+}
+
+function safeCall(fn: () => void): void {
+  try {
+    fn();
+  } catch {
+    // Devtools hooks are optional and should never break app rendering.
+  }
+}

package/src/refract/dom.ts

@@ -0,0 +1,122 @@
+import type { Fiber } from "./types.js";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const SVG_TAGS = new Set([
+  "svg", "circle", "ellipse", "line", "path", "polygon", "polyline",
+  "rect", "g", "defs", "use", "text", "tspan", "image", "clipPath",
+  "mask", "pattern", "marker", "linearGradient", "radialGradient", "stop",
+  "foreignObject", "symbol", "desc", "title",
+]);
+
+export type HtmlSanitizer = (html: string) => string;
+export type UnsafeUrlPropChecker = (key: string, value: unknown) => boolean;
+
+let htmlSanitizer: HtmlSanitizer = identitySanitizer;
+let unsafeUrlPropChecker: UnsafeUrlPropChecker = () => false;
+
+export function setHtmlSanitizer(sanitizer: HtmlSanitizer | null): void {
+  htmlSanitizer = sanitizer ?? identitySanitizer;
+}
+
+export function setUnsafeUrlPropChecker(checker: UnsafeUrlPropChecker | null): void {
+  unsafeUrlPropChecker = checker ?? (() => false);
+}
+
+function identitySanitizer(html: string): string {
+  return html;
+}
+
+/** Create a real DOM node from a fiber */
+export function createDom(fiber: Fiber): Node {
+  if (fiber.type === "TEXT") {
+    return document.createTextNode(fiber.props.nodeValue as string);
+  }
+  const tag = fiber.type as string;
+  const isSvg = SVG_TAGS.has(tag) || isSvgContext(fiber);
+  const el = isSvg
+    ? document.createElementNS(SVG_NS, tag)
+    : document.createElement(tag);
+  applyProps(el as HTMLElement, {}, fiber.props);
+  return el;
+}
+
+/** Check if a fiber is inside an SVG context */
+function isSvgContext(fiber: Fiber): boolean {
+  let f = fiber.parent;
+  while (f) {
+    if (f.type === "svg") return true;
+    if (typeof f.type === "string" && f.type !== "svg" && f.dom) return false;
+    f = f.parent;
+  }
+  return false;
+}
+
+/** Apply props to a DOM element, diffing against old props */
+export function applyProps(
+  el: HTMLElement,
+  oldProps: Record<string, unknown>,
+  newProps: Record<string, unknown>,
+): void {
+  for (const key of Object.keys(oldProps)) {
+    if (key === "children" || key === "key" || key === "ref") continue;
+    if (!(key in newProps)) {
+      if (key.startsWith("on")) {
+        el.removeEventListener(key.slice(2).toLowerCase(), oldProps[key] as EventListener);
+      } else {
+        el.removeAttribute(key);
+      }
+    }
+  }
+
+  for (const key of Object.keys(newProps)) {
+    if (key === "children" || key === "key" || key === "ref") continue;
+    if (oldProps[key] === newProps[key]) continue;
+
+    switch (key) {
+      case "dangerouslySetInnerHTML": {
+        const raw = (newProps[key] as { __html?: unknown } | undefined)?.__html;
+        if (typeof raw !== "string") {
+          throw new TypeError("dangerouslySetInnerHTML expects a string __html value");
+        }
+        el.innerHTML = htmlSanitizer(raw);
+        break;
+      }
+      case "className":
+        el.setAttribute("class", newProps[key] as string);
+        break;
+      case "style":
+        if (typeof newProps[key] === "object" && newProps[key] !== null) {
+          const prevStyles = (typeof oldProps[key] === "object" && oldProps[key] !== null)
+            ? oldProps[key] as Record<string, unknown>
+            : {};
+          const styles = newProps[key] as Record<string, unknown>;
+          for (const prop of Object.keys(prevStyles)) {
+            if (!(prop in styles)) {
+              (el.style as unknown as Record<string, string>)[prop] = "";
+            }
+          }
+          for (const [prop, val] of Object.entries(styles)) {
+            (el.style as unknown as Record<string, string>)[prop] = val == null ? "" : String(val);
+          }
+        } else {
+          el.removeAttribute("style");
+        }
+        break;
+      default:
+        if (key.startsWith("on")) {
+          const event = key.slice(2).toLowerCase();
+          if (oldProps[key]) {
+            el.removeEventListener(event, oldProps[key] as EventListener);
+          }
+          el.addEventListener(event, newProps[key] as EventListener);
+        } else {
+          if (unsafeUrlPropChecker(key, newProps[key])) {
+            el.removeAttribute(key);
+            continue;
+          }
+          el.setAttribute(key, String(newProps[key]));
+        }
+        break;
+    }
+  }
+}

package/src/refract/features/context.ts

@@ -0,0 +1,40 @@
+import type { VNode, Props } from "../types.js";
+import { currentFiber } from "../coreRenderer.js";
+import { createElement, Fragment } from "../createElement.js";
+
+let contextId = 0;
+
+export interface Context<T> {
+  Provider: (props: Props) => VNode;
+  _id: number;
+  _defaultValue: T;
+}
+
+export function createContext<T>(defaultValue: T): Context<T> {
+  const id = contextId++;
+
+  const Provider = (props: Props) => {
+    // Store the context value on the fiber during render
+    const fiber = currentFiber!;
+    if (!fiber._contexts) fiber._contexts = new Map();
+    fiber._contexts.set(id, props.value);
+
+    const children = props.children ?? [];
+    return children.length === 1 ? children[0] : createElement(Fragment, null, ...children);
+  };
+
+  return { Provider, _id: id, _defaultValue: defaultValue };
+}
+
+export function useContext<T>(context: Context<T>): T {
+  const fiber = currentFiber!;
+  // Walk up the fiber tree to find the nearest Provider
+  let f = fiber.parent;
+  while (f) {
+    if (f._contexts?.has(context._id)) {
+      return f._contexts.get(context._id) as T;
+    }
+    f = f.parent;
+  }
+  return context._defaultValue;
+}

package/src/refract/features/hooks.ts

@@ -0,0 +1,145 @@
+import type { Hook } from "../types.js";
+import { currentFiber, scheduleRender } from "../coreRenderer.js";
+import { markPendingEffects } from "../hooksRuntime.js";
+
+function getHook(): Hook {
+  const fiber = currentFiber!;
+  const idx = fiber._hookIndex!;
+  fiber._hookIndex = idx + 1;
+
+  if (idx < fiber.hooks!.length) {
+    return fiber.hooks![idx];
+  }
+  const hook: Hook = { state: undefined };
+  fiber.hooks!.push(hook);
+  return hook;
+}
+
+export function useState<T>(initial: T): [T, (value: T | ((prev: T) => T)) => void] {
+  const hook = getHook();
+  const fiber = currentFiber!;
+
+  // Initialize on first render
+  if (hook.queue === undefined) {
+    hook.state = initial;
+    hook.queue = [];
+  }
+
+  // Process queued updates
+  for (const action of hook.queue as ((prev: T) => T)[]) {
+    hook.state = action(hook.state as T);
+  }
+  hook.queue = [];
+
+  const setState = (value: T | ((prev: T) => T)) => {
+    const action = typeof value === "function"
+      ? value as (prev: T) => T
+      : () => value;
+    (hook.queue as ((prev: T) => T)[]).push(action);
+    scheduleRender(fiber);
+  };
+
+  return [hook.state as T, setState];
+}
+
+type EffectCleanup = void | (() => void);
+
+interface EffectHook extends Hook {
+  state: {
+    effect: () => EffectCleanup;
+    deps: unknown[] | undefined;
+    cleanup?: EffectCleanup;
+    pending: boolean;
+  };
+}
+
+export function useEffect(effect: () => EffectCleanup, deps?: unknown[]): void {
+  const hook = getHook() as EffectHook;
+  const fiber = currentFiber!;
+
+  if (hook.state === undefined) {
+    hook.state = { effect, deps, cleanup: undefined, pending: true };
+    markPendingEffects(fiber);
+  } else {
+    if (depsChanged(hook.state.deps, deps)) {
+      hook.state.effect = effect;
+      hook.state.deps = deps;
+      hook.state.pending = true;
+      markPendingEffects(fiber);
+    } else {
+      hook.state.pending = false;
+    }
+  }
+}
+
+interface RefHook extends Hook {
+  state: { current: unknown };
+}
+
+export function useRef<T>(initial: T): { current: T } {
+  const hook = getHook() as RefHook;
+
+  if (hook.state === undefined) {
+    hook.state = { current: initial };
+  }
+
+  return hook.state as { current: T };
+}
+
+export function useMemo<T>(factory: () => T, deps: unknown[]): T {
+  const hook = getHook();
+
+  if (hook.state === undefined) {
+    hook.state = { value: factory(), deps };
+  } else {
+    const s = hook.state as { value: T; deps: unknown[] };
+    if (depsChanged(s.deps, deps)) {
+      s.value = factory();
+      s.deps = deps;
+    }
+  }
+
+  return (hook.state as { value: T }).value;
+}
+
+export function useCallback<T extends Function>(cb: T, deps: unknown[]): T {
+  return useMemo(() => cb, deps);
+}
+
+export function useReducer<S, A>(
+  reducer: (state: S, action: A) => S,
+  initialState: S,
+): [S, (action: A) => void] {
+  const [state, setState] = useState(initialState);
+  const dispatch = (action: A) => {
+    setState((prev) => reducer(prev, action));
+  };
+  return [state, dispatch];
+}
+
+export function createRef<T = unknown>(): { current: T | null } {
+  return { current: null };
+}
+
+export function useErrorBoundary(): [
+  unknown,
+  () => void,
+] {
+  const [error, setError] = useState<unknown>(null);
+  const fiber = currentFiber!;
+  fiber._errorHandler = (err: unknown) => setError(err);
+  const resetError = () => setError(null);
+  return [error, resetError];
+}
+
+export function depsChanged(
+  oldDeps: unknown[] | undefined,
+  newDeps: unknown[] | undefined,
+): boolean {
+  if (!oldDeps || !newDeps) return true;
+  if (oldDeps.length !== newDeps.length) return true;
+  for (let i = 0; i < oldDeps.length; i++) {
+    if (!Object.is(oldDeps[i], newDeps[i])) return true;
+  }
+  return false;
+}

package/src/refract/features/memoRuntime.ts

@@ -0,0 +1,33 @@
+import type { Fiber } from "../types.js";
+import { registerComponentBailoutHandler } from "../runtimeExtensions.js";
+import { isMemoComponent, type MemoComponent } from "../memoMarker.js";
+
+let registered = false;
+
+export function ensureMemoRuntime(): void {
+  if (!registered) {
+    registered = true;
+    registerComponentBailoutHandler(memoBailoutHandler);
+  }
+}
+
+function memoBailoutHandler(fiber: Fiber): boolean {
+  if (!isMemoComponent(fiber.type)) return false;
+  if (!fiber.alternate) return false;
+
+  const memoComp = fiber.type as MemoComponent;
+  if (!memoComp._compare(fiber.alternate.props, fiber.props)) {
+    return false;
+  }
+
+  // Reuse entire subtree when memo compare passes.
+  fiber.child = fiber.alternate.child;
+  fiber.hooks = fiber.alternate.hooks;
+
+  let child = fiber.child;
+  while (child) {
+    child.parent = fiber;
+    child = child.sibling;
+  }
+  return true;
+}

package/src/refract/features/security.ts

@@ -0,0 +1,61 @@
+import { setHtmlSanitizer as setHtmlSanitizerImpl, setUnsafeUrlPropChecker } from "../dom.js";
+import type { HtmlSanitizer } from "../dom.js";
+
+const URL_ATTRS = new Set(["href", "src", "action", "formaction", "xlink:href"]);
+const BLOCKED_HTML_TAGS = new Set(["script", "iframe", "object", "embed", "link", "meta", "base"]);
+
+function normalizedUrl(value: string): string {
+  return value.replace(/[\u0000-\u0020\u007f]+/g, "").toLowerCase();
+}
+
+function isUnsafeUrl(value: string): boolean {
+  const normalized = normalizedUrl(value);
+  return normalized.startsWith("javascript:") || normalized.startsWith("vbscript:");
+}
+
+function isUnsafeUrlProp(key: string, value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  return URL_ATTRS.has(key.toLowerCase()) && isUnsafeUrl(value);
+}
+
+function defaultHtmlSanitizer(html: string): string {
+  const template = document.createElement("template");
+  template.innerHTML = html;
+
+  const elements = template.content.querySelectorAll("*");
+  for (const element of elements) {
+    const tagName = element.tagName.toLowerCase();
+    if (BLOCKED_HTML_TAGS.has(tagName)) {
+      element.remove();
+      continue;
+    }
+
+    for (const attr of Array.from(element.attributes)) {
+      const attrName = attr.name.toLowerCase();
+      if (attrName.startsWith("on")) {
+        element.removeAttribute(attr.name);
+        continue;
+      }
+
+      if (URL_ATTRS.has(attrName) && isUnsafeUrl(attr.value)) {
+        element.removeAttribute(attr.name);
+      }
+    }
+  }
+
+  return template.innerHTML;
+}
+
+export function setHtmlSanitizer(sanitizer: HtmlSanitizer | null): void {
+  setHtmlSanitizerImpl(sanitizer ?? defaultHtmlSanitizer);
+}
+
+let initialized = false;
+
+export function ensureSecurityDefaults(): void {
+  if (!initialized) {
+    initialized = true;
+    setHtmlSanitizerImpl(defaultHtmlSanitizer);
+    setUnsafeUrlPropChecker(isUnsafeUrlProp);
+  }
+}