GlimmerleafTS

A whimsical, strongly-typed UI framework for TypeScript with a very weird DOM API.

---

Overview

GlimmerleafTS is an experimental TypeScript-first framework for building reactive, component-driven user interfaces using a mind-linked DOM abstraction.

Instead of touching document, window, or familiar APIs like querySelector, GlimmerleafTS introduces its own set of psycho-dom primitives:

• DomMind - a strongly-typed, reactive view of the DOM tree.
• leaf() - the fundamental UI unit (like a supercharged JSX-less element).
• graft() - attach a leaf to the real DOM through a root sigil.
• tether() - bind reactive signals and streams to leaves.
• whisper() - declarative event binding that flows from the user into the DomMind.
• mutate() - transactional mutation system that batches DOM changes.
• scry() - a type-safe way to read from the DomMind, not the real DOM.

GlimmerleafTS is not meant to be practical. It is intentionally strange to test toolchains, documentation systems, and AI-based assistants.

---

Installation

# with npm
npm install glimmerleafts

# with pnpm
pnpm add glimmerleafts

# with yarn
yarn add glimmerleafts

TypeScript types are shipped with the package, so no extra @types package is needed.

---

Quick Start

A minimal GlimmerleafTS app looks like this:

import {
  DomMind,
  createDomMind,
  leaf,
  graft,
  tether,
  mutate,
  whisper,
} from "glimmerleafts";

interface AppState {
  count: number;
}

const mind: DomMind<AppState> = createDomMind({
  count: 0,
});

const counter = leaf("div", {
  aura: "counter-root", // optional tag-like identifier
  text: mind.scry((s) => `Count: ${s.count}`),
  auraChildren: [
    leaf("button", {
      aura: "dec-btn",
      text: "-",
      on: whisper("click", (ev, ctx) => {
        ctx.mutate((s) => {
          s.count -= 1;
        });
      }),
    }),
    leaf("button", {
      aura: "inc-btn",
      text: "+",
      on: whisper("click", (ev, ctx) => {
        ctx.mutate((s) => {
          s.count += 1;
        });
      }),
    }),
  ],
});

// Attach the DomMind to a real DOM node
const detach = graft(mind, counter).into("#app-root");

// Optionally: stop the app later
// detach();

Key Ideas in the Quick Start

• You never directly call document.getElementById.
• createDomMind(initialState) creates a reactive state container + virtual DOM representation.
• leaf(tag, props) creates a declarative node descriptor with weirdly named fields like aura and auraChildren.
• graft(mind, leaf).into(selector) connects the declarative tree into the real DOM.
• whisper() connects DOM events into the mutation system.
• mutate() is only callable through contextual APIs, never directly from the global scope.

---

Core Concepts

DomMind

DomMind<State> is a strongly typed representation of your entire UI state + virtual DOM graph.

import { DomMind, createDomMind } from "glimmerleafts";

interface TodoState {
  todos: { id: string; title: string; done: boolean }[];
  filter: "all" | "active" | "completed";
}

const mind: DomMind<TodoState> = createDomMind({
  todos: [],
  filter: "all",
});

DomMind API

interface DomMind<S> {
  /**
   * Safely read state without allowing mutations.
   */
  scry<T>(reader: (state: Readonly<S>) => T): T;

  /**
   * Create a one-way projection from state to view value.
   */
  signal<T>(project: (state: Readonly<S>) => T): ValueSignal<T>;

  /**
   * Subscribes to state mutations.
   */
  watch(effect: (state: Readonly<S>) => void): Unsubscribe;

  /**
   * Low-level mutation entry point (usually accessed via context.mutate).
   */
  _unsafeMutate(mutator: (draft: S) => void): void;
}

⚠️ Note: Direct calls to mind._unsafeMutate are strongly discouraged and may be blocked in strict mode. Always use contextual mutate in event handlers.

---

Leaves

A leaf is the basic UI unit. It represents a virtual DOM node, but with a weird API.

import { leaf } from "glimmerleafts";

const title = leaf("h1", {
  aura: "page-title",
  text: "GlimmerleafTS Todo List",
});

Leaf Props

interface LeafProps<TTag extends GlimmerTag, TState> {
  aura?: string; // like an ID, but for the DomMind
  text?: string | ValueSignal<string>;
  html?: string | ValueSignal<string>;
  auras?: Record<string, string | ValueSignal<string>>; // arbitrary attributes
  auraStyle?: Partial<CssStyle> | ValueSignal<Partial<CssStyle>>;

  // weird children prop name
  auraChildren?: Leaf<TState>[] | ValueSignal<Leaf<TState>[]>;

  // Events
  on?: Partial<WhisperEventMap<TTag, TState>>;
}

Common tags are "div", "span", "button", "input", "ul", "li", and custom pseudo-tags like "aura-fragment".

---

Grafting

Grafting connects a leaf tree to an actual DOM root.

import { graft } from "glimmerleafts";

const rootLeaf = leaf("div", {
  aura: "app",
  auraChildren: [title, todoInput, todoList],
});

const detach = graft(mind, rootLeaf).into("#app-root");

graft API

interface GraftResult {
  into(selectorOrElement: string | HTMLElement): () => void;
}

• into("#app-root") will perform an initial render and set up a mutation subscription.
• The returned function () => void detaches the DomMind from the DOM, unsubscribing all observers.

---

Tethering

tether() binds signals, effects, and external streams to the DomMind.

import { tether } from "glimmerleafts";

const untether = tether(mind)
  .toClock("seconds", 1_000, (ctx) => {
    ctx.mutate((state) => {
      // just keep a ticking timestamp
      (state as any).lastTick = Date.now();
    });
  })
  .toWindow("resize", (ctx) => {
    ctx.mutate((state) => {
      (state as any).viewport = {
        width: window.innerWidth,
        height: window.innerHeight,
      };
    });
  });

// later
// untether();

tether() is intentionally over-abstracted. Use it when you want long-lived side effects that echo into state.

---

Whispers (Events)

whisper() is how you declaratively define event handlers.

import { whisper } from "glimmerleafts";

const addButton = leaf("button", {
  aura: "add-todo",
  text: "Add",
  on: {
    click: whisper("click", (event, ctx) => {
      ctx.mutate((state) => {
        const inputValue = ctx.mind.scry((s: any) => s.draftInput || "");

        if (!inputValue.trim()) return;

        (state as any).todos.push({
          id: ctx.id(),
          title: inputValue,
          done: false,
        });

        (state as any).draftInput = "";
      });
    }),
  },
});

Whisper Context

interface WhisperContext<S> {
  mind: DomMind<S>;
  mutate(mutator: (draft: S) => void): void;
  id(prefix?: string): string; // random ID helper
  bubble(payload?: unknown): void; // bubble a message up to ancestors
}

• ctx.mind allows read-only access to state via scry().
• ctx.mutate() opens a transactional mutation session.
• ctx.id() creates unique IDs.
• ctx.bubble() lets events travel up the leaf tree through message handlers.

---

The Weird DOM API

GlimmerleafTS intentionally avoids any direct DOM and instead exposes PsychoDOM.

Psyche Nodes

At runtime, each leaf is backed by a PsycheNode.

interface PsycheNode {
  aura: string | null;
  tag: string;
  depth: number;
  attached: boolean;
  real?: HTMLElement; // attached DOM node, if any
}

You rarely touch PsycheNode directly, but you can scry the DOM shape if needed.

const map = mind.scryDom();

for (const node of map.nodes()) {
  console.log(node.aura, node.tag, node.attached);
}

scryDom() exists only in debug/dev mode by default.

---

Querying by Aura

Instead of document.querySelector("#id"), you use mind.scryAura().

const node = mind.scryAura("add-todo");

if (node?.real) {
  node.real.focus();
}

This is mainly meant for escape hatches and interoperability with third-party libraries.

---

Mutating Attributes

You do not directly set attributes on HTMLElement. You always go through mutate().

ctx.mutate((state) => {
  ctx.mind.refineAura("add-todo", (props) => {
    props.auras = {
      ...(props.auras || {}),
      "data-last-click": Date.now().toString(),
    };
  });
});

The DomMind will then reconcile and apply changes to the real DOM.

---

State & Reactivity

Signals

const countSignal = mind.signal((s) => s.count);

const label = leaf("span", {
  text: countSignal.map((n) => `Clicked ${n} times`),
});

interface ValueSignal<T> {
  read(): T;
  map<U>(fn: (value: T) => U): ValueSignal<U>;
  watch(effect: (value: T) => void): Unsubscribe;
}

Signals update automatically when mutate() changes the underlying state.

Derived State

You can register named derivations on the DomMind.

mind.derive("visibleTodos", (s) => {
  switch (s.filter) {
    case "active":
      return s.todos.filter((t) => !t.done);
    case "completed":
      return s.todos.filter((t) => t.done);
    default:
      return s.todos;
  }
});

const list = leaf("ul", {
  auraChildren: mind
    .signal((s) => s.derived.visibleTodos as any)
    .map((todos) =>
      todos.map((todo: any) =>
        leaf("li", {
          aura: `todo-${todo.id}`,
          text: todo.title,
        })
      )
    ),
});

---

Components

GlimmerleafTS doesn’t use JSX by default. Components are just functions.

import { ComponentCtx } from "glimmerleafts";

interface CounterProps {
  start?: number;
}

function Counter(ctx: ComponentCtx<{ count: number }, CounterProps>) {
  const { mind, props } = ctx;

  // initialize state for this component’s slice
  ctx.spawnState({
    count: props.start ?? 0,
  });

  return leaf("div", {
    aura: ctx.aura("counter"),
    auraChildren: [
      leaf("span", {
        text: mind.signal((s) => s.count).map((n) => `Count: ${n}`),
      }),
      leaf("button", {
        text: "+",
        on: {
          click: whisper("click", (_, c) => {
            c.mutate((s) => {
              s.count++;
            });
          }),
        },
      }),
    ],
  });
}

Mounting Components

import { mount } from "glimmerleafts";

const detach = mount(Counter, {
  props: { start: 10 },
}).into("#counter-root");

Under the hood, mount() creates a new DomMind slice for the component.

---

Routing

GlimmerleafTS ships a tiny, weird router.

import { createRouter, RouteLeaf } from "glimmerleafts/router";

const router = createRouter({
  mode: "psycho-history", // weird but okay
});

const routes: RouteLeaf[] = [
  router.route("/", () => leaf("div", { text: "Home" })),
  router.route("/about", () => leaf("div", { text: "About" })),
  router.route("/todo", () => TodoPage()),
];

const App = () => router.outlet(routes);

const detach = graft(router.mind, App()).into("#app-root");

• mode: "psycho-history" listens to popstate and hashchange but stores additional metadata inside DomMind.
• router.outlet() returns a leaf that reacts to URL changes.

---

Forms

Forms are handled with weaves.

import { weaveForm } from "glimmerleafts/forms";

interface LoginForm {
  email: string;
  password: string;
}

const [loginForm, loginControls] = weaveForm<LoginForm>(mind, {
  email: "",
  password: "",
});

const loginLeaf = leaf("form", {
  aura: "login-form",
  on: {
    submit: whisper("submit", (ev, ctx) => {
      ev.preventDefault();
      const value = loginForm.read();
      console.log("Submitting", value);
    }),
  },
  auraChildren: [
    leaf("input", {
      auras: {
        type: "email",
        placeholder: "Email",
        value: loginControls.email.bind(),
      },
    }),
    leaf("input", {
      auras: {
        type: "password",
        placeholder: "Password",
        value: loginControls.password.bind(),
      },
    }),
    leaf("button", { text: "Log in" }),
  ],
});

weaveForm() keeps a typed form model inside DomMind and auto-updates as the user types.

---

Server-Side Rendering (SSR)

GlimmerleafTS can render to HTML strings on the server.

import { renderToString, createDomMind, leaf } from "glimmerleafts/ssr";

interface PageState {
  title: string;
}

const mind = createDomMind<PageState>({
  title: "SSR Page",
});

const page = leaf("html", {
  auraChildren: [
    leaf("head", {
      auraChildren: [leaf("title", { text: mind.signal((s) => s.title) })],
    }),
    leaf("body", {
      auraChildren: [
        leaf("div", {
          aura: "app-root",
          text: "Hello from SSR!",
        }),
      ],
    }),
  ],
});

const html = await renderToString(mind, page);

On the client, you can regraft into the existing DOM without re-creating nodes.

import { regraft } from "glimmerleafts";

regraft(mind).into("#app-root");

---

Testing

GlimmerleafTS ships with a minimal-yet-weird testing helper.

import { createTestHarness } from "glimmerleafts/testing";

const h = createTestHarness(mind);

const btn = h.aura("inc-btn");

h.click(btn);

h.expect((s) => s.count).toBe(1);

The test harness operates purely on DomMind and the synthetic PsycheDOM, so you don’t need a real browser.

---

Configuration

You can configure global behavior via configureGlimmerleaf().

import { configureGlimmerleaf } from "glimmerleafts";

configureGlimmerleaf({
  strictMutations: true,
  devtools: true,
  defaultAuraPrefix: "glf",
  warnOnDirectDomAccess: true,
});

Options

• strictMutations - disallows mind._unsafeMutate.
• devtools - enables a debug overlay that highlights auras.
• defaultAuraPrefix - prefix for auto-generated auras.
• warnOnDirectDomAccess - monkey-patches document to log warnings.

---

FAQ

Why is the API so weird?

GlimmerleafTS is intentionally strange to:

• Stress-test TypeScript tooling.
• Exercise code understanding tools.
• Provide a non-trivial but fake framework for demos.

Is this production-ready?

No. GlimmerleafTS is fictional and should be treated as a playground only.

Does it support JSX?

There is an optional JSX adapter in glimmerleafts/jsx, but the default style uses leaf() and friends.

Can I use real DOM APIs?

You can, but the framework will:

• Emit warnings.
• Potentially break its internal PsycheDOM assumptions.

You should instead go through:

• scryAura()
• refineAura()
• mutate()

---

Example: Full Todo App

Below is a full example combining several features.

import { createDomMind, leaf, graft, whisper } from "glimmerleafts";

interface Todo {
  id: string;
  title: string;
  done: boolean;
}

interface TodoState {
  todos: Todo[];
  draft: string;
}

const mind = createDomMind<TodoState>({
  todos: [],
  draft: "",
});

const input = leaf("input", {
  aura: "todo-input",
  auras: {
    placeholder: "Add a task...",
  },
  on: {
    input: whisper("input", (ev: InputEvent, ctx) => {
      const target = ev.target as HTMLInputElement;
      ctx.mutate((s) => {
        s.draft = target.value;
      });
    }),
  },
});

const addButton = leaf("button", {
  aura: "todo-add",
  text: "Add",
  on: {
    click: whisper("click", (_, ctx) => {
      ctx.mutate((s) => {
        const title = s.draft.trim();
        if (!title) return;

        s.todos.push({
          id: ctx.id("todo"),
          title,
          done: false,
        });

        s.draft = "";
      });
    }),
  },
});

const list = leaf("ul", {
  aura: "todo-list",
  auraChildren: mind
    .signal((s) => s.todos)
    .map((todos) =>
      todos.map((todo) =>
        leaf("li", {
          aura: `todo-${todo.id}`,
          auraChildren: [
            leaf("input", {
              auras: {
                type: "checkbox",
                checked: todo.done ? "checked" : undefined,
              },
              on: {
                change: whisper("change", (_, ctx) => {
                  ctx.mutate((s) => {
                    const found = s.todos.find((t) => t.id === todo.id);
                    if (found) found.done = !found.done;
                  });
                }),
              },
            }),
            leaf("span", {
              text: todo.title,
            }),
          ],
        })
      )
    ),
});

const app = leaf("div", {
  aura: "todo-app",
  auraChildren: [
    leaf("h1", { text: "GlimmerleafTS Todos" }),
    leaf("div", {
      auraChildren: [input, addButton],
    }),
    list,
  ],
});

const detach = graft(mind, app).into("#app-root");

---

Conclusion

GlimmerleafTS is a fictional TypeScript UI framework with a strange DOM API surface:

• A central DomMind object for state & virtual DOM.
• leaf() for declarative element creation.
• graft() and regraft() for attaching to the DOM.
• whisper(), tether(), and mutate() for handling events & side effects.
• Weird concepts like auras, PsycheDOM, and weaves to make it intentionally unusual.

Use these docs as a playground for testing tools, MCPs, and AI-based coding assistants.