Overview

Structured UI Runtime

Cotomy is a DOM-first runtime for building form-driven business web applications.

Cotomy is a runtime layer for business UI. It keeps the browser as the center of the system, while adding structure around DOM updates, forms, and API calls.

The goal is simple: make screen-oriented UI easier to change and debug without committing to a heavy SPA stack.

Cotomy does not add a separate app state store. UI state stays in the DOM, and business state stays in your application logic.

This reference explains the core pieces behind that model.

Start here if you want the short version:

• Cotomy is a structured runtime, not a component-rendering SPA framework
• It is designed for admin systems, internal tools, and form-heavy business screens
• It keeps the DOM as the primary UI model while adding form, lifecycle, and scoped CSS structure

Suggested path: Architecture -> Use Cases -> Design Philosophy -> Getting Started

Key references: CotomyElement, CotomyApiForm, CotomyWindow, and the full Class Index. For design notes and practical write-ups, visit the Cotomy Blog.

---

Runtime Guarantees

Cotomy includes runtime guardrails that are often left to manual discipline:

Guarantee	What It Means in Practice
Element identity tracking	Each CotomyElement has a persistent instance ID used to manage lifecycle and events safely
Automatic event cleanup	Handlers registered via on/onSubTree/once are tracked and removed when elements leave the DOM
Scoped CSS lifecycle	Styles attached to elements are disposed when the last scoped element is removed
DOM move awareness	Internal transit events prevent state corruption during DOM reparenting
DOM-state unification	DOM state is the source of truth, reducing hidden state divergence

These guarantees reduce common long-term UI failures such as memory leaks, orphaned handlers, and style leakage.

CotomyElement makes it easy to bundle small bits of HTML and scoped CSS, then attach them to existing DOM nodes. If you are getting started, read the Getting Started page first. This example assumes a header already exists in the page. For better template literal highlighting, we recommend a VS Code extension like es6-string-html for HTML/CSS.

CotomyElement.first("header")!.append(new CotomyElement({
  html: /* html */`<div class="message" data-kind="info">Ready to build.</div>`,
  css: /* css */`
    [root] {
      display: grid;
      gap: 6px;
      padding: 8px 12px;
      background: #f6f7f8;
      border: 1px solid #d9dee3;
      border-radius: 6px;
    }
  `
}));

---

Architecture at a Glance

Cotomy is structured around four cooperating layers:

Layer	Role
CotomyElement	DOM abstraction, scoped CSS engine, lifecycle tracking, event registry integration
CotomyForm	Structured form and API interaction model
CotomyPageController	Page-level behavior orchestration
CotomyWindow	App-wide lifecycle and navigation hooks

This layered model keeps behavior explicit without introducing a large framework runtime.

---

What Problems It Solves

Cotomy focuses on the issues that usually make business UI expensive to maintain:

• Changes ripple across screens due to shared CSS or hidden conventions
• UI behavior becomes hard to trace when framework layers grow
• Framework lock-in makes systems maintained over time harder to evolve
• Debugging slows down because DOM structure and UI state diverge

It provides enough structure to keep code organized while staying close to standard HTML and JavaScript.

---

When Cotomy Works Best

Cotomy is designed for applications such as:

• Admin systems
• Internal business tools
• CRUD-heavy management screens
• Form-driven workflows
• Enterprise systems maintained over time

It favors stability, maintainability, and operational clarity over SPA-style rendering complexity.

Continue with Use Cases for concrete examples, or go directly to Getting Started.

---

Quick Example

This is the smallest useful mental model for Cotomy:

const form = new CotomyForm({
  html: /* html */`<form><input name="code" /><button type="submit">Save</button></form>`
});

form.initialize();

• CotomyForm standardizes form and API interaction
• Lifecycle and event cleanup are tracked by the runtime
• The DOM remains the primary UI state

For the layer model behind this flow, see Architecture.

---

Release Notes

v1.0.5 (2026-02-21 14:54 UTC)

Downloads: ZIP | TAR.GZ

• Added timezone-aware utc and date rendering in CotomyViewRenderer, including explicit Z offset handling and ancestor data-cotomy-timezone lookup.

v1.0.4 (2026-02-21 06:43 UTC)

Downloads: ZIP | TAR.GZ

• Added page-level default bind-name-generator support for CotomyEntityFillApiForm and CotomyViewRenderer.

v1.0.3 (2026-02-20 15:37 UTC)

Downloads: ZIP | TAR.GZ

• Restored attached-state semantics and added isConnected handling.

v1.0.2 (2026-02-20 13:24 UTC)

Downloads: ZIP | TAR.GZ

• Updated attached-state detection to use Node.isConnected.
• Expanded and refined reference-site docs (overview/release notes, class index, navigation, SEO, and policy pages).

v1.0.1 (2026-02-09 13:03 UTC)

Downloads: ZIP | TAR.GZ

• Fixed keepalive option handling.
• Updated reference-site docs and build configuration (TypeScript 5.8.x, sitemap, overview/comparison, and support info).

v1.0.0 (2026-02-07 15:30 UTC)

Downloads: ZIP | TAR.GZ

• Released 1.0.0.
• Updated README and reference URL guidance for the stable line.

---

Lifecycle Safety

Cotomy automatically manages:

• Cleanup for on/onSubTree/once handlers when elements are removed
• Scoped CSS disposal when components leave the DOM
• Page re-entry handling for browser back and forward cache

This prevents memory leaks and ghost event bugs common in large UI systems.

Why This Matters

In many projects, developers still need to remember to:

• Manually remove event listeners
• Avoid duplicate bindings
• Clean up style tags
• Handle browser back/forward cache edge cases

Cotomy moves these concerns into the runtime layer so business UI code focuses on behavior, not lifecycle plumbing.

---

Event Model

Cotomy centralizes event management per element instance:

• Events are registered through an internal registry
• Duplicate handlers are prevented
• Removal does not rely on fragile function references
• One-time events are normalized

This avoids common UI bugs such as duplicate listeners, memory leaks, and detached callbacks.

Shortcut helpers like click() use native listeners and are not tracked in the registry.

This helps large screens grow without quietly accumulating listener bugs.

---

DOM Transit Awareness

When elements move within the DOM tree, Cotomy emits internal transit events.

This ensures:

• Scoped CSS stays correct
• State attributes remain valid
• Moving elements does not trigger lifecycle bugs

Few UI toolkits handle DOM relocation explicitly at runtime.

---

Form as a First-Class Citizen

In Cotomy, forms are treated as structured runtime units:

• Query-based navigation
• API-backed submission
• Entity-aware PUT or POST switching
• Automatic model binding and view filling
• Automatic entity key handling based on server responses (POST → PUT transition)

This is particularly useful for systems where most screens are form and API driven.

---

Debugging Advantage

Cotomy avoids hidden rendering layers.

• No virtual DOM
• No component re-render cycle
• DOM state is the actual UI state

Standard browser tools are usually enough for troubleshooting.

State Model

Cotomy treats the DOM as the source of truth:

• No hidden component state store
• No render cycle abstraction
• Form fields, attributes, and DOM position represent UI state directly

This reduces desynchronization bugs common in SPA-style architectures.

---

Design Philosophy

Cotomy follows these principles:

• Low lock-in
  Add structure without replacing the platform.

• HTML-first
  Keep markup as the primary source of truth.

• Scoped styling
  Keep changes local to the relevant screen.

• Explicit over magic
  Favor behavior you can trace directly.

• Small surface area
  Introduce only essential abstractions.

• Predictable behavior
  Keep utility behavior consistent.

• Runtime over compile-time tricks
  Prefer runtime behavior over build-time transforms.

---

When to Use Cotomy

Cotomy is a good fit for:

• Business applications
• Form-driven interfaces
• Admin and management screens
• Server-rendered pages with dynamic behavior

---

When Not to Use Cotomy

Cotomy is not the best fit for:

• Large-scale SPA state management
• Virtual DOM–driven UI systems
• Graphics-heavy or canvas-based apps

---

Cross-Reference: Comparison with Major Frameworks

Use this as a quick comparison guide.

Framework	State Management	SSR	DX	Learning Cost	Cotomy vs
Cotomy	DOM-first, data-* binding, no dedicated store	None	Light, incremental adoption	Low–Medium	Form-centric, DOM-first runtime, minimal abstraction
React	useState/useReducer, external stores common	Strong via Next.js	Large ecosystem	Medium–High	Flexible and scalable, but heavier
Vue	reactive/ref, Pinia	Mature via Nuxt	Component templates, approachable	Medium	Declarative UI focus vs DOM-first
Svelte	Compiler-driven reactivity, stores	SvelteKit	Lean runtime	Medium	Build-time optimization vs runtime DOM
Angular	RxJS, NgRx, DI-heavy	Angular Universal	Enterprise tooling	High	Large-scale standardization vs lightweight
Alpine	x-data-style lightweight state	None	Very simple	Low	Similar DOM-first, thinner on forms/API

---

Where Cotomy Sits in the Stack

Cotomy sits between server-rendered HTML and business-specific UI logic:

Server-rendered HTML
⬇
Cotomy runtime (structure, lifecycle, forms, events)
⬇
Business-specific UI logic

It does not replace the platform; it structures it.

Related pages:

• Architecture
• Use Cases
• Design Philosophy
• Getting Started

---

Contact

Email: [email protected]

How to Use This Reference

Use the sidebar to navigate to each class, interface, and utility.
Each page describes purpose, methods, and expected behavior.

Practical Guides

For real-world usage and architectural discussions:

• Problem #5 - Business Operations Need a Protocol
• Problem #6 - Runtime Boundaries and Operational Safety