Forem: Yuuichi Eguchi

Calyx vs cmux: Choosing the Right Ghostty-Based Terminal for macOS 26

Yuuichi Eguchi — Sun, 08 Mar 2026 15:56:53 +0000

The Ghostty Terminal Race

With the rise of AI coding agents in 2026, terminals are no longer just text windows -- they're command centers. Two Ghostty-based macOS terminals have emerged as frontrunners: cmux and Calyx.

Both leverage Ghostty's GPU-accelerated rendering, but they take very different approaches to what a modern terminal should be. Let's break down why Calyx might be the better choice for your daily workflow.

What is cmux?

cmux by manaflow-ai is a terminal built for AI coding agents. It features vertical tabs, notification rings, split panes, a socket API, and deep integration with tools like Claude Code, Codex, and Aider.

What is Calyx?

Calyx is a macOS 26+ native terminal that prioritizes daily-driver polish: a beautiful Liquid Glass UI, robust session management, intuitive tab organization, and security-conscious browser integration.

Head-to-Head Comparison

1. Native macOS 26 Design

Calyx is built from the ground up for macOS 26's Liquid Glass design language. Glass Material is applied to the sidebar, tab bar, command palette, and browser toolbar, making Calyx feel like a first-class citizen on your Mac. It also respects the "Reduce Transparency" accessibility setting, automatically falling back to a solid UI for users who need it.

cmux uses a functional UI but doesn't adopt macOS 26's design system. If you care about visual consistency with the rest of your OS, Calyx wins here.

2. Tab Groups vs Vertical Tabs

cmux offers vertical tabs with useful metadata like git branch, PR status, and listening ports in the sidebar.

Calyx takes tab management further with tab groups. Organize tabs by project or context with 10 color presets. Groups are collapsible in the sidebar, support tab reordering within groups, and show tab counts per group. Double-click a group header to rename it, close individual tabs or an entire group directly from the sidebar. Working on a full-stack app? Group your frontend, backend, and infrastructure tabs separately. With dozens of tabs open, you'll always know where you are.

3. Split Panes: Stability Matters

Both terminals support split panes, but stability differs significantly.

cmux has known rendering issues where terminal panes fail to render after closing splits. Keyboard shortcuts also reportedly break after opening browser tabs.

Calyx's splits are backed by an immutable binary tree data structure (SplitTree) with horizontal/vertical splitting, drag-to-resize with a 50px minimum pane guarantee, equalize operation, and spatial focus navigation (left/right/up/down). Tab switching uses only setFocus + refresh, keeping the render loop stable by design. No phantom blank panes, no lost keyboard input.

4. Command Palette

Hit Cmd+Shift+P in Calyx and you get a VS Code-style command palette with fuzzy search across 15 built-in commands. The scoring system combines word-start bonus, consecutive match bonus, exact match bonus, and prefix match bonus for accurate results. Command usage frequency is tracked, so your most-used commands rise to the top over time.

The shortcut system is built on a low-level NSEvent monitor that detects IME compose state. CJK input never triggers shortcuts accidentally. Text fields and text views are also properly excluded.

cmux doesn't have a command palette.

5. Session Persistence

Quit Calyx and reopen it. Your tabs, tab groups, split layouts, browser URLs, and window positions are fully restored.

Under the hood, Calyx implements atomic file writes (temp file + rename), automatic backup rotation, 2-second debounced auto-save, schema versioning (currently v3) with migration support, crash loop detection (max 3 recovery attempts), and window frame clamping to screen bounds. If the primary session file is corrupted, it automatically recovers from the backup.

6. Notification System

Both terminals support notifications, but Calyx emphasizes security and reliability.

Calyx relays OSC notifications to UNUserNotificationCenter with per-tab unread badges (circle in sidebar, capsule in tab bar, capped at 99+). It implements rate limiting (max 5 per second per tab), Dock icon bounce on first unread, and automatic badge clearing on window focus.

Notification text is sanitized with bidi override removal, control character filtering, zero-width character removal, newline normalization, NFC normalization, and truncation at 256 grapheme clusters, preventing malicious terminal sequences from becoming attack vectors.

7. Browser Integration That Works

Both terminals include a built-in browser. However, cmux has reported issues with HTTP connections being blocked and forced dark mode on all pages.

Calyx's browser uses a non-persistent WebKit data store for privacy, with back/forward/reload navigation, a loading indicator, error banners, and JavaScript dialog support (alert, confirm, prompt).

Security is comprehensive:

URL scheme validation (only http/https/about at top-level)
Subresource scheme blocking (javascript, data)
Redirect depth limiting (max 10)
Download filename sanitization (null byte stripping, dangerous character replacement, dangerous extension blocking, 255-char limit)
MIME type blocking for dangerous executables
Symlink traversal prevention on download paths
Automatic macOS Quarantine attribute on downloaded files

8. Licensing

Calyx's MIT license places no restrictions on commercial use or modification. cmux's AGPL requires source code disclosure if you provide the software as a network service, a potential blocker for enterprise adoption.

9. Git Source Control

Calyx includes a built-in Git source control view directly in the sidebar. Switch to the "Changes" mode and you get a complete overview of your repository's state without leaving the terminal.

Working Changes: Files grouped into Staged / Unstaged / Untracked sections with status badges (M/A/D/R/C/?/U/T)
Commit Graph: Color-coded branch lane visualization with commit history. Click to expand and see changed files per commit. Infinite scroll pagination for large repositories
Inline Diff Viewer: Click any file to open a diff tab with color-coded additions (green), deletions (red), and hunk headers (cyan). Dual old/new line number gutter. Binary file detection and automatic truncation for diffs over 1MB or 50,000 lines
Diff Review Comments: Click the + button next to any line number to add an inline comment. Submit Review sends the formatted review directly to a Claude Code or Codex terminal tab

No more switching to VS Code just to review what Claude Code changed. It's all inside Calyx.

cmux doesn't have this feature.

10. AI Agent IPC (Inter-Process Communication)

Calyx includes a built-in MCP server that enables AI agent instances (Claude Code, Codex CLI) to communicate with each other across tabs and panes.

Just run "Enable AI Agent IPC" from the command palette, and every agent instance in Calyx can discover peers, send messages, broadcast announcements, and check for incoming messages via 7 MCP tools. Config is auto-written to ~/.claude.json and ~/.codex/config.toml when the respective tool is installed. Thanks to the MCP spec instructions field, agents automatically register as peers upon connecting.

Calyx's MCP-based IPC is purpose-built for multi-agent collaboration across Claude Code and Codex.

11. Scriptable Browser

cmux pioneered browser automation with 80+ CLI commands for controlling WKWebView. Calyx now matches this with 25 CLI commands for browser scripting: snapshot accessibility trees, click elements, fill forms, evaluate JavaScript, take screenshots, wait for conditions, inspect DOM attributes, list links and inputs, check visibility, hover, and scroll.

The calyx CLI binary is bundled inside the app. Run Install CLI to PATH from the command palette to make it available system-wide.

calyx browser list
calyx browser snapshot --tab-id <id>
calyx browser get-text h1 --tab-id <id>
calyx browser click a --tab-id <id>
calyx browser eval 'document.title' --tab-id <id>
calyx browser get-attribute a href         # Get element attribute
calyx browser get-links                    # List all links (JSON)
calyx browser get-inputs                   # List form inputs (JSON)
calyx browser is-visible '#el'             # Check visibility
calyx browser hover '#menu'                # Hover element
calyx browser scroll down --amount 500     # Scroll page/element

Element refs (@e1, @e2) from snapshots can be used as selectors in subsequent commands, enabling reliable DOM automation even on dynamic pages.

Feature Matrix

Feature	Calyx	cmux
Liquid Glass UI	Yes	No
Tab Groups (color-coded)	Yes	No (vertical tabs only)
Split Panes	Yes, stable	Rendering bugs
Command Palette	Yes (fuzzy search + frequency)	No
Session Persistence	Yes (schema v3 + crash recovery)	No
Browser Integration	Yes (security validation + downloads)	No HTTP, forced dark mode
Notifications	Yes (rate-limited + sanitized)	Yes
CJK Input Handling	Yes (IME-aware shortcuts)	Unknown
Multi-Window	Yes	Yes
Git Source Control	Yes (commit graph + diff viewer)	No
AI Agent IPC (MCP)	Yes (7 tools, auto-register, Claude Code + Codex)	No
Scriptable Browser	Yes (25 CLI commands)	Yes (80+ CLI commands)
License	MIT	AGPL

The Bottom Line

cmux is a solid terminal with a sharp focus on AI agent workflows.

But as a daily-driver terminal, Calyx offers a more polished and reliable experience: a beautiful native Liquid Glass UI, intuitive color-coded tab groups, stable split panes backed by immutable data structures, a fuzzy-search command palette with frequency learning, crash-resilient session persistence, a scriptable browser with 25 CLI commands, rate-limited and sanitized notifications, proper CJK input handling, and a permissive MIT license.

If you're on macOS 26, give Calyx a try.

Links

d3motap3 — A Multi-Source Video Recorder for macOS That Captures Phone + PC Screens Simultaneously

Yuuichi Eguchi — Wed, 04 Mar 2026 12:49:31 +0000

Why I Built This

When recording tool demos, I often needed to capture a phone screen and a PC screen at the same time. In practice, that meant recording them separately and syncing them up in post to make it look simultaneous.

Another pain point was re-recording every time I made a typo or missed a step. Doing that over and over was genuinely frustrating.

I built d3motap3 to solve both of these problems.

What It Does

Capture Up to 2 Sources at Once

Phone and display, terminal and webcam — any combination in side-by-side or picture-in-picture.

There are 7 source types to choose from:

Full display
Individual window
Screen region
Webcam
Built-in terminal
iOS device (USB)
Android device (USB)

YAML Scripted Automation

Define your demo steps in YAML and it records itself. Each step waits for the previous one to finish, so timing is always perfect. Define it once, get a perfect recording every time.

steps:
  - type: terminal_input
    text: "npm install"
  - type: wait_for_output
    pattern: "added .* packages"
  - type: terminal_input
    text: "npm start"
  - type: wait_for_output
    pattern: "Server running"

Timeline Editor

Edit your recordings with the built-in editor:

Clip splitting
Transitions (fade / dissolve / wipe)
Text overlays with animation
Audio track import and editing

AI Script Generation

Describe your demo in plain text and get a YAML script generated via Claude API.

Built-in Terminal Rendered in Rust

The built-in terminal isn't a screenshot — it's rendered directly by Rust via PTY → alacritty VT parser → cosmic-text. The terminal itself becomes a capture source, so there's no need to window-capture an external terminal app.

3 Layouts

Single — one source, full frame
Side-by-Side — two sources next to each other (adjustable split ratio)
Picture-in-Picture — a small overlay on top of the main source (adjustable position and size)

Platform

macOS only (uses ScreenCaptureKit). Distributed as a signed and notarized DMG.

Approve Claude Code Permission Requests from Your Phone

Yuuichi Eguchi — Sun, 22 Feb 2026 06:43:06 +0000

The Problem

Claude Code asks for permission before running tools like Bash, Write, and Edit. This is a great safety feature — but it means you have to be sitting at your terminal to press "y".

Step away for coffee? Claude Code stalls until you get back.

The Solution

claude-remote-approver sends each permission request as a push notification to your phone via ntfy.sh. Tap Approve or
Deny, and Claude Code continues immediately — no terminal required.

How It Works

  Claude Code
    │
    │  PermissionRequest hook (stdin JSON)
    ▼
  claude-remote-approver hook
    │
    ├──POST──▶ ntfy.sh/          ──push──▶  Phone (ntfy app)
    │                                                 │
    │                                           Approve / Deny tap
    │                                                 │
    └──SSE───▶ ntfy.sh/-response  ◀──POST──┘
    │
    │  stdout JSON: { "behavior": "allow" } or { "behavior": "deny" }
    ▼
  Claude Code continues or stops

It uses ntfy.sh, an open-source HTTP-based pub-sub notification service. No account required. The topic name is a 128-bit random string, so only you can receive the notifications.

Setup (3 Steps)

1. Install the ntfy app on your phone

2. Install and run setup on your PC

  npm install -g claude-remote-approver
  claude-remote-approver setup

3. Scan the QR code

The setup command prints a QR code in your terminal. Scan it with the ntfy app to subscribe.

Important: Start a new Claude Code session after setup. The hook is loaded at session startup, so existing sessions won't pick it up.

How It Feels

Once set up, just use Claude Code normally. When a permission request fires:

Your phone buzzes with a notification showing the tool name and a summary (e.g., Bash: npm install express)
Tap Approve or Deny
Claude Code continues instantly

If you don't respond within the timeout (default: 120 seconds), the request is automatically denied. Fail-closed by design.

Sample notification

Other Commands

  claude-remote-approver test      # Send a test notification
  claude-remote-approver status    # Show current config
  claude-remote-approver disable   # Temporarily disable
  claude-remote-approver enable    # Re-enable
  claude-remote-approver uninstall # Remove everything

Security

Topic names are generated with crypto.randomBytes(16) (128 bits of entropy)
Config file is created with permission 0600 (owner-only)
For sensitive work, you can self-host ntfy instead of using the public server

Links

Give it a try and let me know what you think!

Constela: Built-in a11y Checks, Plugin System & CSS Transitions

Yuuichi Eguchi — Sun, 08 Feb 2026 07:30:25 +0000

What's New in Constela

Constela is a JSON-based declarative UI framework — you write your entire UI in JSON, and the compiler + runtime handles the rest. We're shipping three features that make Constela apps more accessible, extensible, and polished.

1. Compile-Time Accessibility Checks

Accessibility shouldn't be an afterthought. Constela now checks your JSON programs for common a11y issues at compile time and reports them as warnings.

7 Built-in Rules

Code	What it catches
`IMG_NO_ALT`	Images without `alt` text
`BUTTON_NO_LABEL`	Buttons with no text or `aria-label`
`ANCHOR_NO_LABEL`	Links with no text or `aria-label`
`INPUT_NO_LABEL`	Inputs without a label
`HEADING_SKIP`	Skipped heading levels (h1 → h3)
`POSITIVE_TABINDEX`	Positive `tabindex` values
`DUPLICATE_ID`	Duplicate `id` attributes

These are warnings, not errors — your code still compiles, so you can adopt them gradually.

const result = compile(myProgram);
if (result.ok && result.warnings?.length) {
  result.warnings.forEach(w => console.warn(`[${w.code}] ${w.message}`));
}

2. Plugin System

Want to use custom functions in your JSON DSL? Now you can.

Define a Plugin

import type { ConstelaPlugin } from '@constela/core';

const myPlugin: ConstelaPlugin = {
  name: 'my-analytics',
  version: '1.0.0',
  globalFunctions: {
    trackEvent: (category: string, action: string) => { /* ... */ },
    formatCurrency: (amount: number) => `$${amount.toFixed(2)}`,
  },
};

export default myPlugin;

Register It

Add to constela.config.json:

{
  "plugins": ["my-analytics", "./src/plugins/local-plugin"]
}

That's it — your functions are now available in the DSL.

Safety features:

Atomic registration (all-or-nothing)
Prototype pollution protection (__proto__, constructor, prototype blocked)
Works in both client and server rendering

3. CSS Class-Based Transitions

Conditional rendering (if nodes) now supports smooth enter/exit animations:

{
  "kind": "if",
  "condition": { "expr": "state", "name": "showToast" },
  "then": {
    "kind": "element",
    "tag": "div",
    "children": [
      { "kind": "text", "value": { "expr": "lit", "value": "Saved!" } }
    ]
  },
  "transition": {
    "enter": "slide-in",
    "enterActive": "slide-in-active",
    "exit": "slide-out",
    "exitActive": "slide-out-active",
    "duration": 250
  }
}

Pair it with CSS:

.slide-in { transform: translateY(-20px); opacity: 0; }
.slide-in-active { transition: all 250ms ease; transform: translateY(0); opacity: 1; }
.slide-out { transform: translateY(0); opacity: 1; }
.slide-out-active { transition: all 250ms ease; transform: translateY(-20px); opacity: 0; }

The runtime handles:

Enter flow: create element → apply enter → next frame: swap to enterActive → cleanup
Exit flow: apply exit → next frame: swap to exitActive → remove element
Fast toggling: cancels in-progress animations gracefully
SSR: transitions are ignored server-side (no changes needed)

Try It Out

npm install @constela/core @constela/compiler @constela/runtime @constela/start
npx constela dev

Check out the Language Specification for the full DSL reference, or browse the Examples to see these features in action.

Links:

Constela New Features - Islands Architecture, Realtime Features, and New UI Components

Yuuichi Eguchi — Sat, 07 Feb 2026 12:55:44 +0000

Introduction

We're excited to announce new features for Constela, with 7 major new capabilities that significantly improve performance and developer experience:

Theme System (CSS variables, light/dark/system modes)
Islands Architecture (6 hydration strategies)
Streaming SSR (3 flush strategies)
Realtime Features (SSE, optimistic updates, state binding)
New UI Components (DatePicker, Calendar, Tree, Accordion, DataTable, VirtualScroll, Chart)

Feature 1: Theme System

We've introduced a CSS variable-based theme system with support for light/dark/system modes and shadcn/ui-compatible color tokens.

{
  "theme": {
    "mode": "system",
    "colors": {
      "primary": "hsl(220 90% 56%)",
      "primary-foreground": "hsl(0 0% 100%)",
      "background": "hsl(0 0% 100%)",
      "foreground": "hsl(222 47% 11%)",
      "muted": "hsl(210 40% 96%)",
      "border": "hsl(214 32% 91%)"
    },
    "darkColors": {
      "background": "hsl(222 47% 11%)",
      "foreground": "hsl(210 40% 98%)",
      "muted": "hsl(217 33% 17%)",
      "border": "hsl(217 33% 17%)"
    },
    "fonts": {
      "sans": "Inter, system-ui, sans-serif",
      "mono": "JetBrains Mono, monospace"
    },
    "cssPrefix": "app"
  }
}

Key Features

System Theme Detection: Automatic prefers-color-scheme detection
Persistence: localStorage + Cookie support (SSR-safe)
CSS Variables: Auto-applies prefixed variables like --app-primary to :root
Dark Class: Automatically manages dark class on document.documentElement

Feature 2: Islands Architecture

We've implemented Islands Architecture for partial hydration. Choose from 6 hydration strategies to drastically reduce your initial JS bundle.

{
  "kind": "island",
  "id": "interactive-chart",
  "strategy": "visible",
  "strategyOptions": {
    "threshold": 0.5,
    "rootMargin": "100px"
  },
  "content": {
    "kind": "component",
    "name": "Chart",
    "props": { "data": { "expr": "state", "name": "chartData" } }
  },
  "state": {
    "chartData": { "type": "list", "initial": [] }
  },
  "actions": [
    {
      "name": "loadData",
      "steps": [
        { "do": "fetch", "url": { "expr": "lit", "value": "/api/chart-data" }, "result": "data", "onSuccess": [
          { "do": "set", "target": "chartData", "value": { "expr": "var", "name": "data" } }
        ]}
      ]
    }
  ]
}

Hydration Strategies

Strategy	Description	Use Case
`load`	Hydrate immediately on page load	Critical interactive elements
`idle`	Hydrate when browser is idle	Non-urgent interactions
`visible`	Hydrate when element enters viewport	Below-the-fold content
`interaction`	Hydrate on first user interaction	Lazy-loaded widgets
`media`	Hydrate when media query matches	Responsive components
`never`	Never hydrate	Static content only

Build Optimization

Islands are automatically code-split:

dist/
  _islands/
    interactive-chart.js   # Island-specific bundle
    sidebar-menu.js
  client.js                # Main bundle

Feature 3: Realtime Features

We've added SSE (Server-Sent Events) connections, optimistic updates, and state binding.

SSE Connections

{
  "do": "sseConnect",
  "connection": "notifications",
  "url": { "expr": "lit", "value": "/api/events" },
  "eventTypes": ["message", "update"],
  "reconnect": {
    "enabled": true,
    "strategy": "exponential",
    "maxRetries": 5,
    "baseDelay": 1000
  },
  "onMessage": [
    { "do": "update", "target": "messages", "operation": "push", "value": { "expr": "var", "name": "payload" } }
  ]
}

Optimistic Updates

Update UI immediately with automatic rollback on server error:

{
  "name": "likePost",
  "steps": [
    {
      "do": "optimistic",
      "target": "posts",
      "path": { "expr": "var", "name": "index" },
      "value": { "expr": "lit", "value": { "liked": true } },
      "result": "updateId",
      "timeout": 5000
    },
    {
      "do": "fetch",
      "url": { "expr": "concat", "items": [
        { "expr": "lit", "value": "/api/posts/" },
        { "expr": "var", "name": "postId" },
        { "expr": "lit", "value": "/like" }
      ]},
      "method": "POST",
      "onSuccess": [
        { "do": "confirm", "id": { "expr": "var", "name": "updateId" } }
      ],
      "onError": [
        { "do": "reject", "id": { "expr": "var", "name": "updateId" } }
      ]
    }
  ]
}

Feature 4: Streaming SSR

We've implemented ReadableStream-based streaming SSR with Edge Runtime support for significantly reduced TTFB. Just enable it in your config - no TypeScript required.

Configuration

{
  "streaming": {
    "enabled": true,
    "flushStrategy": "batched"
  }
}

Flush Strategies

Strategy	Description
`immediate`	Flush each chunk immediately
`batched`	Batch flush at 1KB threshold (default)
`manual`	Flush only at the end (small pages)

Suspense Boundaries

Use suspense nodes for async content with loading states:

{
  "kind": "suspense",
  "id": "user-profile",
  "fallback": {
    "kind": "element",
    "tag": "div",
    "props": { "className": { "expr": "lit", "value": "skeleton" } }
  },
  "content": {
    "kind": "component",
    "name": "UserProfile"
  }
}

The server renders the fallback immediately, then streams the actual content when ready - all configured declaratively in JSON.

Feature 5: New UI Components

DatePicker / Calendar

{
  "kind": "component",
  "name": "DatePicker",
  "props": {
    "value": { "expr": "state", "name": "selectedDate" },
    "onChange": { "event": "change", "action": "updateDate" },
    "format": { "expr": "lit", "value": "yyyy-MM-dd" },
    "locale": { "expr": "lit", "value": "en-US" }
  }
}

Tree / Accordion

{
  "kind": "component",
  "name": "Tree",
  "props": {
    "items": { "expr": "state", "name": "treeData" },
    "onSelect": { "event": "select", "action": "handleSelect" },
    "expandedKeys": { "expr": "state", "name": "expanded" }
  }
}

DataTable

Full-featured table with sorting, filtering, and pagination:

{
  "kind": "component",
  "name": "DataTable",
  "props": {
    "data": { "expr": "state", "name": "users" },
    "columns": { "expr": "lit", "value": [
      { "key": "name", "title": "Name", "sortable": true },
      { "key": "email", "title": "Email", "filterable": true },
      { "key": "status", "title": "Status" }
    ]},
    "pageSize": { "expr": "lit", "value": 10 },
    "sortable": { "expr": "lit", "value": true },
    "filterable": { "expr": "lit", "value": true }
  }
}

VirtualScroll

{
  "kind": "component",
  "name": "VirtualScroll",
  "props": {
    "items": { "expr": "state", "name": "largeList" },
    "itemHeight": { "expr": "lit", "value": 50 },
    "containerHeight": { "expr": "lit", "value": 400 },
    "overscan": { "expr": "lit", "value": 5 }
  }
}

Chart (7 Types)

{
  "kind": "component",
  "name": "BarChart",
  "props": {
    "data": { "expr": "state", "name": "chartData" },
    "valueKey": { "expr": "lit", "value": "value" },
    "labelKey": { "expr": "lit", "value": "label" },
    "showGrid": { "expr": "lit", "value": true }
  }
}

Supported chart types: bar, line, pie, donut, area, radar, scatter

Summary

This update brings significant enhancements for modern web application development:

Performance: Islands Architecture reduces bundle size, Streaming SSR improves TTFB
DX: Theme system makes dark mode easy, realtime features enable declarative sync logic
UI: Feature-rich UI components boost development efficiency

Try it out today!

Introducing AI-Powered UI Generation for Constela

Yuuichi Eguchi — Tue, 27 Jan 2026 13:29:51 +0000

Introduction

Constela is a JSON-first declarative UI framework. With this release, we're adding AI-powered features to supercharge your development workflow:

DSL Generator: Generate Constela JSON from natural language prompts
Security Validation: Automatically validate generated DSL for safety
CLI suggest command: Analyze existing DSL and get improvement suggestions

Installation

npm install @constela/ai

Features

1. Build-time Component Generation

Use type: "ai" in the data section to generate components at build time:

{
  "version": "1.0",
  "data": {
    "card": {
      "type": "ai",
      "provider": "anthropic",
      "prompt": "A card component with title, description, and action button",
      "output": "component"
    }
  },
  "view": {
    "kind": "component",
    "name": "card",
    "props": {
      "title": { "expr": "lit", "value": "Welcome" },
      "description": { "expr": "lit", "value": "Get started" }
    }
  }
}

The AI generates a component like:

{
  "kind": "element",
  "tag": "div",
  "props": {
    "className": { "expr": "lit", "value": "card" }
  },
  "children": [
    {
      "kind": "element",
      "tag": "h2",
      "children": [
        { "kind": "text", "value": { "expr": "param", "name": "title" } }
      ]
    },
    {
      "kind": "element",
      "tag": "p",
      "children": [
        { "kind": "text", "value": { "expr": "param", "name": "description" } }
      ]
    },
    {
      "kind": "element",
      "tag": "button",
      "props": {
        "onClick": { "event": "click", "action": "handleAction" }
      },
      "children": [
        { "kind": "text", "value": { "expr": "lit", "value": "Action" } }
      ]
    }
  ]
}

2. Security Validation

All generated DSL is automatically validated against security rules.

Forbidden Tags (blocked by default):

script, iframe, object, embed, form

Forbidden Actions (cannot be whitelisted):

import, call, dom

Restricted Actions (require explicit whitelist):

fetch

3. CLI suggest Command

Analyze existing DSL files and get AI-powered improvement suggestions:

# Analyze for accessibility issues
constela suggest app.json --aspect accessibility

# Analyze for security (using OpenAI)
constela suggest app.json --aspect security --provider openai

# JSON output for tooling
constela suggest app.json --aspect ux --json

Example output:

=== Suggestions for app.json (accessibility) ===

[HIGH] Missing aria-label on button
   Recommendation: Add aria-label="Submit form" to the button element
   Location: view.children[0].props

[MED] Low color contrast in text
   Recommendation: Increase contrast ratio to meet WCAG AA standards
   Location: view.children[2].props.style

Total: 2 suggestion(s)

4. Runtime Dynamic Generation

Use the generate action step to create DSL in response to user input:

{
  "version": "1.0",
  "state": {
    "userPrompt": { "type": "string", "initial": "" },
    "generatedCard": { "type": "object", "initial": {} }
  },
  "actions": [
    {
      "name": "generateCard",
      "steps": [
        {
          "do": "generate",
          "provider": "anthropic",
          "prompt": { "expr": "state", "name": "userPrompt" },
          "output": "component",
          "result": "generatedCard",
          "onSuccess": [
            {
              "do": "set",
              "target": "card",
              "value": { "expr": "var", "name": "generatedCard" }
            }
          ],
          "onError": [
            {
              "do": "set",
              "target": "error",
              "value": { "expr": "lit", "value": "Generation failed" }
            }
          ]
        }
      ]
    }
  ],
  "view": {
    "kind": "element",
    "tag": "div",
    "children": [
      {
        "kind": "element",
        "tag": "input",
        "props": {
          "type": { "expr": "lit", "value": "text" },
          "value": { "expr": "state", "name": "userPrompt" },
          "onInput": { "event": "input", "action": "updatePrompt" }
        }
      },
      {
        "kind": "element",
        "tag": "button",
        "props": {
          "onClick": { "event": "click", "action": "generateCard" }
        },
        "children": [
          { "kind": "text", "value": { "expr": "lit", "value": "Generate" } }
        ]
      }
    ]
  }
}

Environment Variables

Create a .env file in your project root and add your API key:

# For Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-...

# For OpenAI
OPENAI_API_KEY=sk-...

Make sure .env is in your .gitignore to avoid committing secrets.

How It Works

Prompt Processing: Your natural language description is sent to the AI provider
DSL Generation: The AI generates valid Constela JSON based on the language specification
Security Validation: Generated DSL is validated against security rules
Error Handling: Any validation errors are reported with actionable fixes

Conclusion

With @constela/ai, you can leverage AI to:

Generate JSON DSL from natural language
Automatically validate security
Get improvement suggestions for existing code

Check out the official documentation for more details.

Links:

Introducing @constela/ui - Copy-Paste UI Components for Constela JSON DSL

Yuuichi Eguchi — Sun, 25 Jan 2026 07:03:52 +0000

Introducing @constela/ui

I'm excited to announce the release of @constela/ui - a UI component library for Constela JSON DSL.

This library provides copy-paste UI components that you can drop directly into your Constela projects. All components are written in JSON format - no TypeScript or React knowledge required for customization.

Installation

npm install @constela/ui

Available Components

Basic (7)

Button - 6 variants, 4 sizes
Input - Text input field
Textarea - Multi-line text input
Select - Dropdown selection
Checkbox - Checkbox input
Radio - Radio button
Switch - Toggle switch

Feedback (5)

Alert - Alert messages (default, destructive)
Card - Card container
Badge - Inline badge
Skeleton - Loading placeholder
Avatar - User avatar with fallback

Overlay (4)

Dialog - Modal dialog with proper ARIA
Tooltip - Hover tooltip
Popover - Click-triggered popover
Toast - Notifications (default, success, error, warning, info)

Navigation/Layout (6)

Tabs - Tab navigation
Breadcrumb - Breadcrumb navigation
Pagination - Page pagination
Container - Max-width container
Grid - CSS Grid layout
Stack - Flexbox stack

How to Use

1. Copy Component Files

Copy the components you need from node_modules/@constela/ui/components/:

button/
├── button.constela.json   # Component definition
└── button.styles.json     # Style preset

2. Import Styles

Add the style preset to your application's styles section.

3. Use the Component

{
  "kind": "component",
  "name": "Button",
  "props": {
    "variant": { "expr": "lit", "value": "default" },
    "size": { "expr": "lit", "value": "lg" }
  },
  "children": [
    { "kind": "text", "value": { "expr": "lit", "value": "Click me" } }
  ]
}

The Style System

Each component uses a CVA-like style system with base classes, variants, and default variants:

{
  "buttonStyles": {
    "base": "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
    "variants": {
      "variant": {
        "default": "bg-primary text-primary-foreground hover:bg-primary/90",
        "destructive": "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        "outline": "border border-input bg-background hover:bg-accent",
        "secondary": "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        "ghost": "hover:bg-accent hover:text-accent-foreground",
        "link": "text-primary underline-offset-4 hover:underline"
      },
      "size": {
        "default": "h-10 px-4 py-2",
        "sm": "h-9 rounded-md px-3",
        "lg": "h-11 rounded-md px-8",
        "icon": "h-10 w-10"
      }
    },
    "defaultVariants": {
      "variant": "default",
      "size": "default"
    }
  }
}

Dynamic Styling with StyleExpr

Components use StyleExpr to apply styles dynamically based on props:

{
  "className": {
    "expr": "style",
    "preset": "buttonStyles",
    "props": {
      "variant": { "expr": "param", "name": "variant" },
      "size": { "expr": "param", "name": "size" }
    }
  }
}

Accessibility First

All components include proper ARIA attributes:

aria-label for screen reader labels
aria-disabled for disabled state indication
role for semantic roles (dialog, alert, tablist, etc.)
aria-live for live region announcements

Example: Dialog Component

{
  "params": {
    "open": { "type": "boolean", "required": false },
    "title": { "type": "string", "required": false }
  },
  "view": {
    "kind": "element",
    "tag": "div",
    "props": {
      "role": { "expr": "lit", "value": "dialog" },
      "aria-modal": { "expr": "lit", "value": "true" },
      "className": { "expr": "style", "preset": "dialogStyles" }
    },
    "children": [{ "kind": "slot" }]
  }
}

Customization

Adding New Variants

Edit the style file to add new variants:

{
  "variants": {
    "variant": {
      "success": "bg-green-500 text-white hover:bg-green-600"
    }
  }
}

Extending Parameters

Add new parameters to the component definition. All parameters are optional by default, so existing usage won't break.

Modifying Base Styles

Change the base property to modify styles that apply to all variants.

Test Coverage

All components are verified with 563 tests covering:

Structure validation
Parameter validation
Style preset validation
Accessibility attributes

cd packages/ui && pnpm test

# Test Files  passed (22)
#      Tests  563 passed (563)

What's Next

Component catalog page on the official website
More components based on community feedback
Enhanced animation support

Conclusion

@constela/ui provides a solid foundation for building UIs with Constela JSON DSL. The copy-paste approach makes it simple to get started, and the JSON-based format makes customization accessible to everyone.

Give it a try and let me know what you think!

Constela: Call, Lambda, and Array Expressions for Type-Safe Data Operations

Yuuichi Eguchi — Sat, 24 Jan 2026 16:18:15 +0000

Introduction

We are excited to announce the latest update to Constela, bringing call expressions, lambda expressions, and the new array expressions to our compiler-first UI language. This update enables powerful data transformations and dynamic array construction while maintaining the security and determinism that define Constela.

What is Constela?

Constela is a compiler-first UI language designed for AI-generated UI. Unlike React or Next.js where you write UI with JavaScript, Constela uses a constrained JSON DSL that is validated, analyzed, and compiled into minimal runtime code.

	Constela	React / Next.js
UI authoring	JSON DSL	JavaScript / JSX
Execution	compiler-driven	runtime-driven
State updates	declarative actions	arbitrary JS
Errors	structured errors	runtime exceptions

Highlights

This release introduces three major expression types:

Call Expression - Method calls on arrays, strings, Math, and Date
Lambda Expression - Anonymous functions for array higher-order methods
Array Expression - Dynamic array construction from expressions

Package Versions:

@constela/core: 0.15.2
@constela/compiler: 0.14.2
@constela/runtime: 0.18.3
@constela/server: 11.0.1

Call Expression

The call expression enables method invocation on target values with a clean, declarative syntax.

Syntax

{
  "expr": "call",
  "target": <Expression>,
  "method": "<method_name>",
  "args": [<Expression>, ...]
}

Basic Examples

Get array length:

{
  "expr": "call",
  "target": { "expr": "state", "name": "items" },
  "method": "length"
}

Get element at index:

{
  "expr": "call",
  "target": { "expr": "state", "name": "items" },
  "method": "at",
  "args": [{ "expr": "lit", "value": 0 }]
}

Check if array includes a value:

{
  "expr": "call",
  "target": { "expr": "lit", "value": [1, 2, 3] },
  "method": "includes",
  "args": [{ "expr": "lit", "value": 2 }]
}

String Operations

Convert to uppercase:

{
  "expr": "call",
  "target": { "expr": "state", "name": "username" },
  "method": "toUpperCase"
}

Split string into array:

{
  "expr": "call",
  "target": { "expr": "lit", "value": "react,typescript,node" },
  "method": "split",
  "args": [{ "expr": "lit", "value": "," }]
}

Trim whitespace:

{
  "expr": "call",
  "target": { "expr": "state", "name": "userInput" },
  "method": "trim"
}

Math Operations

Calculate minimum value:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Math" },
  "method": "min",
  "args": [
    { "expr": "lit", "value": 0 },
    { "expr": "state", "name": "count" }
  ]
}

Round a calculated value:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Math" },
  "method": "round",
  "args": [
    {
      "expr": "bin",
      "op": "*",
      "left": { "expr": "state", "name": "price" },
      "right": { "expr": "lit", "value": 1.1 }
    }
  ]
}

Date Operations

Get current timestamp:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Date" },
  "method": "now"
}

Lambda Expression

The lambda expression enables anonymous functions for array higher-order methods like filter, map, find, and more.

Syntax

{
  "expr": "lambda",
  "param": "<parameter_name>",
  "index": "<index_name>",  // optional
  "body": <Expression>
}

Filter Example

Filter items greater than a threshold:

{
  "expr": "call",
  "target": { "expr": "lit", "value": [1, 2, 3, 4, 5] },
  "method": "filter",
  "args": [
    {
      "expr": "lambda",
      "param": "x",
      "body": {
        "expr": "bin",
        "op": ">",
        "left": { "expr": "var", "name": "x" },
        "right": { "expr": "lit", "value": 2 }
      }
    }
  ]
}

Result: [3, 4, 5]

Map Example

Double each element:

{
  "expr": "call",
  "target": { "expr": "lit", "value": [1, 2, 3] },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "x",
      "body": {
        "expr": "bin",
        "op": "*",
        "left": { "expr": "var", "name": "x" },
        "right": { "expr": "lit", "value": 2 }
      }
    }
  ]
}

Result: [2, 4, 6]

Using Index Parameter

Map with index:

{
  "expr": "call",
  "target": { "expr": "lit", "value": ["a", "b", "c"] },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "item",
      "index": "i",
      "body": { "expr": "var", "name": "i" }
    }
  ]
}

Result: [0, 1, 2]

Accessing Object Properties

Extract names from user objects:

{
  "expr": "call",
  "target": { "expr": "state", "name": "users" },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "user",
      "body": {
        "expr": "get",
        "base": { "expr": "var", "name": "user" },
        "path": "name"
      }
    }
  ]
}

Supported Methods

Array Methods

Method	Description	Example
`length`	Get array length	`items.length()`
`at`	Get element at index (supports negative)	`items.at(-1)`
`includes`	Check if element exists	`items.includes(value)`
`slice`	Extract subarray	`items.slice(1, 3)`
`indexOf`	Find index of element	`items.indexOf("foo")`
`join`	Join elements into string	`items.join(", ")`
`filter`	Filter by predicate (lambda)	`items.filter(x => x > 0)`
`map`	Transform elements (lambda)	`items.map(x => x * 2)`
`find`	Find first matching (lambda)	`items.find(x => x.id === 1)`
`findIndex`	Find index of first matching	`items.findIndex(x => x > 5)`
`some`	Check if any match	`items.some(x => x > 10)`
`every`	Check if all match	`items.every(x => x > 0)`

String Methods

Method	Description	Example
`length`	Get string length	`str.length()`
`charAt`	Get character at index	`str.charAt(0)`
`substring`	Extract substring	`str.substring(0, 5)`
`slice`	Extract with negative index support	`str.slice(-3)`
`split`	Split into array	`str.split(",")`
`trim`	Remove whitespace	`str.trim()`
`toUpperCase`	Convert to uppercase	`str.toUpperCase()`
`toLowerCase`	Convert to lowercase	`str.toLowerCase()`
`replace`	Replace first occurrence	`str.replace("a", "b")`
`includes`	Check substring exists	`str.includes("foo")`
`startsWith`	Check prefix	`str.startsWith("http")`
`endsWith`	Check suffix	`str.endsWith(".json")`
`indexOf`	Find substring index	`str.indexOf("@")`

Math Methods

Method	Description	Example
`min`	Get minimum value	`Math.min(a, b, c)`
`max`	Get maximum value	`Math.max(0, count)`
`round`	Round to nearest integer	`Math.round(3.7)`
`floor`	Round down	`Math.floor(3.9)`
`ceil`	Round up	`Math.ceil(3.1)`
`abs`	Absolute value	`Math.abs(-5)`
`sqrt`	Square root	`Math.sqrt(16)`
`pow`	Power	`Math.pow(2, 3)`
`random`	Random 0-1	`Math.random()`
`sin` / `cos` / `tan`	Trigonometric functions	`Math.sin(0)`

Date Methods

Method	Description	Example
`now`	Current timestamp (ms)	`Date.now()`
`parse`	Parse date string	`Date.parse("2024-01-01")`
`toISOString`	ISO format string	`date.toISOString()`
`getTime`	Get timestamp	`date.getTime()`
`getFullYear`	Get year	`date.getFullYear()`

Practical Examples

1. Filtering a TODO List

Display only incomplete tasks:

{
  "version": "1.0",
  "state": {
    "todos": {
      "type": "list",
      "initial": [
        { "id": 1, "text": "Learn Constela", "completed": true },
        { "id": 2, "text": "Build app", "completed": false },
        { "id": 3, "text": "Deploy", "completed": false }
      ]
    },
    "showCompleted": { "type": "boolean", "initial": false }
  },
  "view": {
    "kind": "each",
    "items": {
      "expr": "cond",
      "if": { "expr": "state", "name": "showCompleted" },
      "then": { "expr": "state", "name": "todos" },
      "else": {
        "expr": "call",
        "target": { "expr": "state", "name": "todos" },
        "method": "filter",
        "args": [
          {
            "expr": "lambda",
            "param": "todo",
            "body": {
              "expr": "not",
              "operand": {
                "expr": "get",
                "base": { "expr": "var", "name": "todo" },
                "path": "completed"
              }
            }
          }
        ]
      }
    },
    "as": "todo",
    "body": {
      "kind": "element",
      "tag": "div",
      "children": [
        {
          "kind": "text",
          "value": {
            "expr": "get",
            "base": { "expr": "var", "name": "todo" },
            "path": "text"
          }
        }
      ]
    }
  }
}

2. Search Filter with Case-Insensitive Matching

{
  "expr": "call",
  "target": { "expr": "state", "name": "products" },
  "method": "filter",
  "args": [
    {
      "expr": "lambda",
      "param": "product",
      "body": {
        "expr": "call",
        "target": {
          "expr": "call",
          "target": {
            "expr": "get",
            "base": { "expr": "var", "name": "product" },
            "path": "name"
          },
          "method": "toLowerCase"
        },
        "method": "includes",
        "args": [
          {
            "expr": "call",
            "target": { "expr": "state", "name": "searchQuery" },
            "method": "toLowerCase"
          }
        ]
      }
    }
  ]
}

3. Chaining Methods

Filter then map:

{
  "expr": "call",
  "target": {
    "expr": "call",
    "target": { "expr": "lit", "value": [1, 2, 3, 4, 5] },
    "method": "filter",
    "args": [
      {
        "expr": "lambda",
        "param": "x",
        "body": {
          "expr": "bin",
          "op": ">",
          "left": { "expr": "var", "name": "x" },
          "right": { "expr": "lit", "value": 2 }
        }
      }
    ]
  },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "x",
      "body": {
        "expr": "bin",
        "op": "*",
        "left": { "expr": "var", "name": "x" },
        "right": { "expr": "lit", "value": 2 }
      }
    }
  ]
}

Result: [6, 8, 10]

4. Dynamic Array Construction (Array Expression)

The new array expression enables dynamic array construction:

{
  "expr": "array",
  "elements": [
    { "expr": "var", "name": "basicSetup" },
    {
      "expr": "call",
      "target": { "expr": "var", "name": "json" },
      "method": "apply",
      "args": []
    }
  ]
}

This is equivalent to JavaScript's [basicSetup, json()].

Combining with state and literals:

{
  "expr": "array",
  "elements": [
    { "expr": "state", "name": "config" },
    { "expr": "lit", "value": "default" },
    { "expr": "var", "name": "customPlugin" }
  ]
}

Nested arrays:

{
  "expr": "array",
  "elements": [
    {
      "expr": "array",
      "elements": [
        { "expr": "lit", "value": 1 },
        { "expr": "lit", "value": 2 }
      ]
    },
    {
      "expr": "array",
      "elements": [
        { "expr": "lit", "value": 3 },
        { "expr": "lit", "value": 4 }
      ]
    }
  ]
}

5. Value Clamping

Ensure a value stays within bounds:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Math" },
  "method": "min",
  "args": [
    { "expr": "lit", "value": 100 },
    {
      "expr": "call",
      "target": { "expr": "var", "name": "Math" },
      "method": "max",
      "args": [
        { "expr": "lit", "value": 0 },
        { "expr": "state", "name": "value" }
      ]
    }
  ]
}

Security Measures

Constela takes security seriously. All method calls are protected by multiple layers of defense:

1. Whitelist-Based Method Filtering

Only explicitly allowed methods can be called. Attempting to call a non-whitelisted method returns undefined:

{
  "expr": "call",
  "target": { "expr": "lit", "value": "hello" },
  "method": "constructor"  // Not allowed - returns undefined
}

The whitelist is defined at compile time and cannot be bypassed at runtime.

2. Prototype Pollution Prevention

Constela prevents access to prototype chain methods that could be used for injection attacks:

__proto__ access is blocked
constructor access is blocked
prototype access is blocked

3. Type-Aware Method Resolution

Methods are resolved based on the target value type, preventing type confusion attacks:

{
  "expr": "call",
  "target": { "expr": "lit", "value": 123 },
  "method": "toUpperCase"  // Returns undefined - numbers don't have this method
}

4. Safe Null/Undefined Handling

Calling methods on null or undefined returns undefined gracefully without throwing:

{
  "expr": "call",
  "target": { "expr": "state", "name": "nonexistent" },
  "method": "length"  // Returns undefined
}

Conclusion

This update to Constela brings powerful data transformation and array construction capabilities while maintaining the security-first approach that defines the framework. Call, lambda, and array expressions enable:

Declarative data transformations - Filter, map, and transform data without JavaScript
Dynamic array construction - Build arrays from variables, function results, and expressions
Type-safe operations - Compile-time validation ensures correct usage
Secure by default - Whitelist-based method filtering prevents injection attacks
Composable expressions - Chain operations for complex transformations

Getting Started

# Create a new Constela project
npx create-constela my-app
cd my-app
npm run dev

Resources

We are excited to see what you build with Constela!

Constela is MIT licensed. Contributions welcome!

Introducing the Constela VSCode Extension - Build UIs with JSON

Yuuichi Eguchi — Sat, 24 Jan 2026 07:22:06 +0000

Introducing the Constela VSCode Extension

I'm excited to announce the release of the official VSCode extension for Constela - a JSON-based UI DSL that compiles to minimal runtime JavaScript.

Install from VSCode Marketplace

What is Constela?

Constela is a declarative UI framework where you define your entire application in JSON. No complex JavaScript, no JSX - just pure, structured JSON that describes your UI, state, and interactions.

Here's a simple counter example:

{
  "version": "1.0",
  "state": {
    "count": { "type": "number", "initial": 0 }
  },
  "actions": [
    {
      "name": "increment",
      "steps": [
        { "do": "update", "name": "count", "with": "increment" }
      ]
    }
  ],
  "view": {
    "node": "element",
    "tag": "button",
    "props": {
      "onClick": { "action": "increment" }
    },
    "children": [
      {
        "node": "text",
        "content": { "expr": "state", "name": "count" }
      }
    ]
  }
}

Learn more at constela.dev

Extension Features

Syntax Highlighting

The extension provides full syntax highlighting for .constela.json files:

Expression types: lit, state, var, bin, cond, get, concat, and more
Action steps: set, update, fetch, navigate, delay, interval, etc.
View nodes: element, text, if, each, component, slot, etc.

IntelliSense Auto-completion

Get smart completions as you type:

Type "expr": " to see all available expression types
Type "do": " to see all action step types
Type "node": " to see all view node types
Reference completions for your defined state, actions, and components

Real-time Validation

Errors appear instantly as you type, powered by the Constela compiler:

JSON syntax errors
Missing required fields
Undefined state/action/component references
Type mismatches

Hover Documentation

Hover over any keyword to see its documentation, including:

Signature and structure
Description and usage
Available options

Go to Definition

Use Ctrl+Click (or Cmd+Click on macOS) to jump to:

State field definitions
Action definitions
Component definitions

Installation

Open VSCode
Go to Extensions (Ctrl+Shift+X)
Search for "Constela"
Click Install

Or install directly from the VSCode Marketplace.

Getting Started

Create a new file with the .constela.json extension
Start with the basic structure shown above
Enjoy syntax highlighting and real-time validation!

Technical Details

The extension uses the Language Server Protocol (LSP) for a robust editing experience:

Validation Engine: Full Constela compiler integration
Bundle Size: ~160KB (all dependencies included)
Zero External Dependencies: Everything is bundled with esbuild

Why Constela?

No Build Step Complexity: JSON is your source of truth
Type-Safe by Design: The compiler catches errors before runtime
Minimal Runtime: Compiles to optimized JavaScript
AI-Friendly: JSON structure is perfect for AI-assisted development

Feedback

Found a bug or have a feature request? Please open an issue on GitHub.

Give Constela a try and let me know what you think!

Introducing create-constela: Bootstrap Constela Projects in Seconds

Yuuichi Eguchi — Wed, 21 Jan 2026 23:21:45 +0000

TL;DR

npx create-constela my-app
cd my-app
npm run dev

Three commands. That's all you need to start building with Constela.

What is create-constela?

create-constela is a scaffolding CLI tool for Constela projects. Similar to create-next-app or create-vite, it lets you bootstrap a new project with a single command.

Features

Interactive mode: Choose project name and package manager interactively
Template selection: Start with examples using the --example option
Flexible options: Skip git initialization or dependency installation as needed

Usage

Basic Usage

npx create-constela my-app

This command will:

Prompt you to select a package manager (npm / yarn / pnpm)
Create the project directory
Copy template files
Initialize git repository
Install dependencies

CLI Options

Option	Description
`--example <name>`	Use a specific example template
`--template <name>`	Use a specific template
`--list`	List available templates and examples
`--no-git`	Skip git initialization
`--no-install`	Skip dependency installation
`--package-manager <pm>`	Specify package manager (npm/yarn/pnpm)

Examples

# List available templates
npx create-constela --list

# Create with a specific example
npx create-constela my-app --example counter

# Skip git and install
npx create-constela my-app --no-git --no-install

# Use pnpm
npx create-constela my-app --package-manager pnpm

Generated Project Structure

my-app/
├── constela.config.json
├── package.json
├── .gitignore
└── src/
    └── routes/
        └── index.json

The generated index.json gives you a minimal starting point:

{
  "version": "1.0",
  "state": {},
  "actions": [],
  "view": {
    "kind": "element",
    "tag": "div",
    "children": [
      {
        "kind": "element",
        "tag": "h1",
        "children": [
          { "kind": "text", "value": { "expr": "lit", "value": "Welcome to Constela" } }
        ]
      }
    ]
  }
}

What is Constela?

Constela is a compiler-first UI language designed for AI-generated UIs.

Unlike React or Next.js, you don't write UI with JavaScript. Instead, you describe UI behavior as a constrained JSON DSL, which is validated, analyzed, and compiled into minimal runtime code.

Key Differences

	Constela	React / Next.js
UI authoring	JSON DSL	JavaScript / JSX
Execution	compiler-driven	runtime-driven
State updates	declarative actions	arbitrary JS
Errors	structured errors	runtime exceptions

Performance Comparison

We rebuilt Constela's official website using both Constela and Next.js:

Metric	Constela	Next.js	Difference
Build time	2.2s	12.3s	5.6× faster
node_modules size	297MB	794MB	2.7× smaller
Output size	14MB	72MB	5.1× smaller

Technical Implementation

create-constela is built with:

commander.js: CLI argument parsing
@inquirer/prompts: Interactive prompts
Node.js fs API: File copying and transformation
TDD: 163 test cases ensuring quality

Security

Path traversal protection is built-in. Malicious inputs like ../../../etc/passwd are rejected at the template resolution layer.

Getting Started

Ready to try Constela? Run:

npx create-constela my-app
cd my-app
npm run dev

Open http://localhost:3000 and start building!

Links

Have questions or feedback? Drop a comment below!

Constela: Built-in SEO Features for JSON-Driven UI

Yuuichi Eguchi — Tue, 20 Jan 2026 15:01:56 +0000

We're excited to announce comprehensive SEO features for Constela, our JSON DSL-based UI framework. If you're building websites with Constela, you can now easily optimize for search engines without leaving the declarative JSON approach.

What is Constela?

Constela is a compiler-first UI language where you describe UI behavior as JSON DSL instead of JavaScript. It's designed for AI-generated UI, deterministic behavior, and inspectable state transitions. Learn more

New SEO Features

1. HTML lang Attribute

Configure the lang attribute in constela.config.json:

{
  "seo": {
    "lang": "en"
  }
}

Output: <html lang="en">

We support the full BCP 47 specification, including:

Basic: en, ja, zh
Regional: en-US, en-GB
Script: zh-Hans-CN, zh-Hant-TW
Extended: de-DE-u-co-phonebk

2. Canonical URLs

Set canonical URLs via route.canonical with full expression support:

{
  "route": {
    "path": "/posts/:slug",
    "canonical": {
      "expr": "bin",
      "op": "+",
      "left": { "expr": "lit", "value": "https://example.com" },
      "right": { "expr": "route", "source": "path" }
    }
  }
}

For /posts/hello-world, this generates:

<link rel="canonical" href="https://example.com/posts/hello-world">

Dynamic routes are fully supported - the { "expr": "route", "source": "path" } expression correctly resolves to the actual path during SSG build.

3. JSON-LD Structured Data

Add Schema.org structured data via route.jsonLd:

{
  "route": {
    "jsonLd": {
      "type": "Article",
      "properties": {
        "headline": { "expr": "route", "name": "slug", "source": "param" },
        "author": {
          "expr": "object",
          "type": "Person",
          "properties": {
            "name": { "expr": "lit", "value": "John Doe" }
          }
        },
        "datePublished": { "expr": "lit", "value": "2024-01-15" }
      }
    }
  }
}

Output:

<script type="application/ld+json">
{"@context":"https://schema.org","@type":"Article","headline":"hello-world","author":{"@type":"Person","name":"John Doe"},"datePublished":"2024-01-15"}
</script>

Nested Objects and Arrays

Complex structures like BreadcrumbList are fully supported:

{
  "jsonLd": {
    "type": "BreadcrumbList",
    "properties": {
      "itemListElement": {
        "expr": "array",
        "items": [
          {
            "expr": "object",
            "type": "ListItem",
            "properties": {
              "position": { "expr": "lit", "value": 1 },
              "name": { "expr": "lit", "value": "Home" },
              "item": { "expr": "lit", "value": "https://example.com/" }
            }
          },
          {
            "expr": "object",
            "type": "ListItem",
            "properties": {
              "position": { "expr": "lit", "value": 2 },
              "name": { "expr": "lit", "value": "Blog" },
              "item": { "expr": "lit", "value": "https://example.com/blog" }
            }
          }
        ]
      }
    }
  }
}

Security

All SEO features include built-in XSS protection:

lang attribute: BCP 47 format validation (alphanumeric and hyphens only)
Canonical URL: HTML escaping for special characters
JSON-LD: Unicode escaping for </script> and other dangerous sequences

Summary

Constela makes SEO a first-class citizen in JSON-driven UI development:

Feature	Configuration	Output
Language	`seo.lang`	`<html lang="...">`
Canonical	`route.canonical`	`<link rel="canonical">`
Structured Data	`route.jsonLd`	`<script type="application/ld+json">`

All features work seamlessly with dynamic routes and SSG builds.

Links

Have you tried Constela? Let us know your thoughts in the comments!

Edit JSON, See Changes Instantly: HMR in Constela

Yuuichi Eguchi — Sun, 18 Jan 2026 15:27:23 +0000

What is Constela?

Constela is a compiler-first UI framework where you describe UI behavior as JSON instead of JavaScript. No JSX, no hooks, no JavaScript in your components.

{
  "version": "1.0",
  "state": {
    "count": { "type": "number", "initial": 0 }
  },
  "actions": [
    {
      "name": "increment",
      "steps": [{ "do": "update", "target": "count", "operation": "increment" }]
    }
  ],
  "view": {
    "kind": "element",
    "tag": "button",
    "props": { "onClick": { "event": "click", "action": "increment" } },
    "children": [{ "kind": "text", "value": { "expr": "state", "name": "count" } }]
  }
}

The JSON is validated, analyzed, and compiled into minimal runtime code. We added Hot Module Replacement (HMR) to make the development experience even better.

The Problem: Full Reloads Are Painful

Before HMR, every time you saved a JSON file:

The entire page reloaded
Form inputs were cleared
Counter values reset to initial
Scroll position jumped to top

When you're tweaking styles or adjusting text, re-entering test data over and over is frustrating.

The Solution: Edit JSON, Keep Your State

With HMR, you edit JSON and save. That's it. The browser updates instantly while preserving your application state.

Before HMR	After HMR
~500ms (full reload)	~50ms (hot update)
State lost	State preserved
Scroll position lost	Scroll preserved
Form inputs cleared	Form inputs kept

How to Use It

No configuration required. Just start the dev server:

npx constela dev

You'll see:

[Constela] Dev server started at http://localhost:3000
[Constela] HMR server started at ws://localhost:24678

Now edit any JSON file and save. Changes appear instantly.

Real-World Examples

Example 1: Updating Button Text

You have a counter at 10. You want to change the button label.

Before:

{
  "children": [
    { "kind": "text", "value": { "expr": "lit", "value": "Count: " } },
    { "kind": "text", "value": { "expr": "state", "name": "count" } }
  ]
}

After:

{
  "children": [
    { "kind": "text", "value": { "expr": "lit", "value": "Clicks: " } },
    { "kind": "text", "value": { "expr": "state", "name": "count" } }
  ]
}

Save the file. The button now shows "Clicks: 10". The count wasn't reset.

Example 2: Adding New State

You can add new state fields without losing existing values.

Before:

{
  "state": {
    "count": { "type": "number", "initial": 0 }
  }
}

After:

{
  "state": {
    "count": { "type": "number", "initial": 0 },
    "message": { "type": "string", "initial": "Hello!" }
  }
}

The count value is preserved. The new message field gets its initial value.

Example 3: Changing State Types

What if you change a field's type?

{
  "state": {
    "count": { "type": "string", "initial": "" }
  }
}

Constela detects the type mismatch and shows a warning:

[HMR] Type mismatch for state 'count': number -> string. Using new initial value.

The old number value can't be used as a string, so the new initial value is used instead. This prevents bugs from incompatible types.

Error Handling

If you make a mistake in your JSON, Constela shows a clear error overlay:

┌────────────────────────────────────────────┐
│            Compilation Error               │
│                                            │
│  /src/routes/index.json                    │
│                                            │
│  ┌────────────────────────────────────┐   │
│  │ UNDEFINED_STATE                     │   │
│  │ Undefined state reference: 'cont'   │   │
│  │ at view.children[0].value.name      │   │
│  │                                     │   │
│  │ Did you mean 'count'?               │   │
│  └────────────────────────────────────┘   │
│                                            │
└────────────────────────────────────────────┘

The overlay shows:

File path: Which file has the error
Error code: UNDEFINED_STATE, SCHEMA_INVALID, etc.
Error message: What went wrong
JSON path: Where in the JSON structure
Suggestion: "Did you mean 'count'?" when applicable

Fix the error and save. The overlay disappears and your app is back.

How It Works (Brief Overview)

Under the hood, HMR uses a WebSocket connection between the dev server and browser:

File watcher detects changes to JSON files
Server recompiles the JSON to a program
WebSocket sends the new program to the browser
Browser saves current state, swaps in new program, restores state

The key insight: since Constela programs are pure JSON with explicit state declarations, we can safely serialize and restore state across updates.

What Triggers HMR

HMR works for:

Route JSON files (src/routes/**/*.json)
Component JSON files
Layout JSON files (src/layouts/**/*.json)

These require a full reload:

TypeScript files (API routes, middleware)
Configuration files
Adding new route files

Summary

Constela brings HMR that just works:

Zero config: npx constela dev and you're done
State preserved: Form inputs, counters, scroll positions survive updates
Instant feedback: Changes appear in ~50ms
Clear errors: Overlay shows exactly what's wrong and how to fix it
Auto-reconnect: Connection loss is handled gracefully

The philosophy of Constela is "build websites with JSON, not JavaScript". HMR makes that workflow even smoother.