Adowire — Full Build Plan

A Livewire v4-equivalent reactive component system for AdonisJS v7 + Edge.js Modelled feature-for-feature after Livewire v4

Project Overview
Architecture
Folder Structure
How It Works (The Lifecycle)
Feature Checklist
Build Phases
API Design (Developer-Facing)
VineJS Validation Design
Edge.js Template API
Client-Side Directives
TypeScript Decorators
Security Model
Testing Strategy
Ace Commands Reference
Package Publishing

1. Project Overview

Adowire is a full-stack reactive component library for AdonisJS v7 that brings the developer experience of Livewire v4 to the Node.js ecosystem.

Instead of writing AJAX boilerplate or reaching for a frontend framework, developers write TypeScript classes + Edge.js templates. Adowire handles the network roundtrip, DOM morphing, state management, and event system automatically.

Key Goals

Goal	Description
Zero-JS for developers	Write TypeScript + Edge templates. No manual fetch/axios.
Livewire v4 feature parity	Every Livewire v4 feature has an adowire equivalent
Edge.js native	First-class integration with AdonisJS Edge.js template engine
Alpine.js bridge	Full `$wire` object integration, same as Livewire
TypeScript-first	Decorators, type-safe properties, full IDE support
VineJS validation	Uses AdonisJS's own VineJS for all validation — no external validator
AdonisJS v7 patterns	Providers, Ace commands, IoC container, config files

Tech Stack

Layer	Technology
Server framework	AdonisJS v7
Template engine	Edge.js v6
Validation	VineJS v4 (AdonisJS's official validator)
DOM morphing	`morphdom`
JS companion	Alpine.js v3
Build tool	`tsdown` (Rolldown-based)
Test runner	Japa v5
TypeScript	v5.9+

Why VineJS?

VineJS is AdonisJS's official validation library — it is already a peerDependency of @adonisjs/core, so every AdonisJS app already has it available. Using it means:

Zero extra dependencies for adowire consumers
Native AdonisJS error formatting that matches the rest of the app
Full access to VineJS custom rules, custom messages providers, and metadata API
5–10× faster than Zod/Yup
Handles HTML form serialization quirks natively (strings cast to numbers/booleans, empty strings, etc.)

2. Architecture

┌─────────────────────────────────────────────────────┐
│                    Browser                          │
│                                                     │
│  Edge HTML + wire:* attributes + Alpine $wire       │
│            │                    ▲                   │
│            │ POST /adowire/msg  │ JSON response     │
└────────────┼────────────────────┼───────────────────┘
             │                    │
┌────────────▼────────────────────┼───────────────────┐
│                 AdonisJS Server                     │
│                                                     │
│  WireRequestHandler                                 │
│    │                                                │
│    ├── SnapshotManager  (dehydrate / hydrate)       │
│    ├── ComponentRegistry (discover & resolve)       │
│    ├── WireComponent     (your TS class)            │
│    │     ├── mount / boot / hydrate / dehydrate     │
│    │     ├── updating / updated                     │
│    │     ├── rendering / rendered                   │
│    │     └── exception                              │
│    ├── WireValidator     (VineJS integration)       │
│    │     ├── @Validate decorator → vine schema      │
│    │     ├── validate() method                      │
│    │     ├── rules() method override                │
│    │     └── SimpleMessagesProvider support         │
│    └── Edge.js           (render template → HTML)  │
└─────────────────────────────────────────────────────┘

Request Lifecycle (per AJAX call)

1.  Browser sends POST /adowire/message
    Body: { components: [{ snapshot, calls, updates }] }

2.  Server: verify HMAC checksum on snapshot

3.  Server: hydrate component from snapshot state

4.  Server: run boot() hook

5.  Server: run hydrate() hook

6.  Server: apply property updates (wire:model mutations)
    - for each update:
        - check property is not @Locked
        - run updating(name, value) hook
        - set property
        - run updated(name, value) hook
        - if @Validate(onUpdate: true) on property: run VineJS validation

7.  Server: call action methods
    - check method is public and callable ($isCallable guard)
    - resolve DI params from AdonisJS IoC container
    - call method
    - if @Renderless: set skipRender = true
    - catch ValidationException from VineJS → populate $errors

8.  Server: run dehydrate() hook

9.  Server: if !skipRender → render Edge template → HTML
    - inject morph markers around @if / @each blocks

10. Server: dehydrate new snapshot (HMAC sign)

11. Server: return JSON { components: [{ snapshot, effects }] }
    effects: { html, redirect, dispatches, js, streams, download, title }

12. Browser: morphdom(oldHtml, newHtml)

13. Browser: process effects
    (redirect, dispatch browser events, run JS actions, stream text chunks)

3. Folder Structure

adowire/
│
├── src/                              # Server-side TypeScript source
│   ├── component.ts                  # WireComponent base class
│   ├── component_registry.ts         # Auto-discover + register components
│   ├── snapshot.ts                   # Dehydrate / Hydrate state ↔ JSON
│   ├── morph_markers.ts              # Inject HTML comment markers for morphdom
│   ├── request_handler.ts            # POST /adowire/message endpoint
│   ├── form.ts                       # WireForm base class
│   ├── validator.ts                  # VineJS validation engine wrapper
│   ├── wire_exception.ts             # WireException, ValidationException
│   ├── synthesizers/                 # Custom type serializers
│   │   ├── synthesizer.ts            # Base Synthesizer interface
│   │   ├── date_synthesizer.ts       # Date / DateTime
│   │   ├── map_synthesizer.ts        # Map
│   │   └── set_synthesizer.ts        # Set
│   ├── decorators/                   # TypeScript property/method decorators
│   │   ├── index.ts                  # Re-export all decorators
│   │   ├── computed.ts               # @Computed
│   │   ├── locked.ts                 # @Locked
│   │   ├── validate.ts               # @Validate(schema, opts)
│   │   ├── url.ts                    # @Url
│   │   ├── on.ts                     # @On('event-name')
│   │   ├── reactive.ts               # @Reactive
│   │   ├── modelable.ts              # @Modelable
│   │   ├── lazy.ts                   # @Lazy
│   │   ├── session.ts                # @Session
│   │   ├── async.ts                  # @Async
│   │   ├── renderless.ts             # @Renderless
│   │   ├── defer.ts                  # @Defer
│   │   ├── isolate.ts                # @Isolate
│   │   ├── json.ts                   # @Json
│   │   ├── title.ts                  # @Title
│   │   └── layout.ts                 # @Layout
│   ├── concerns/                     # Mixins / Traits
│   │   ├── with_pagination.ts        # WithPagination mixin
│   │   └── with_file_uploads.ts      # WithFileUploads mixin
│   ├── edge/                         # Edge.js plugin
│   │   ├── plugin.ts                 # Registers all tags + globals
│   │   └── tags/
│   │       ├── wire_styles.ts        # @!wireStyles()
│   │       ├── wire_scripts.ts       # @!wireScripts()
│   │       ├── wire_component.ts     # @adowire('name', props)
│   │       ├── error.ts              # @error('field') / @enderror
│   │       ├── island.ts             # @island / @endisland
│   │       ├── placeholder.ts        # @placeholder / @endplaceholder
│   │       ├── persist.ts            # @persist / @endpersist
│   │       └── teleport.ts           # @teleport / @endteleport
│   ├── testing/
│   │   └── wire_test.ts              # Adowire.test() helper
│   └── types.ts                      # All shared TypeScript interfaces
│
├── client/                           # Browser-side TypeScript → wire.js
│   ├── index.ts                      # Adowire client bootstrap + global API
│   ├── component.ts                  # Client-side component class
│   ├── connection.ts                 # HTTP request pool + queue management
│   ├── morph.ts                      # morphdom integration
│   ├── store.ts                      # Client component state store
│   ├── alpine_bridge.ts              # $wire magic object for Alpine.js
│   └── directives/                   # wire:* attribute handlers
│       ├── index.ts                  # Register all directives
│       ├── model.ts                  # wire:model
│       ├── click.ts                  # wire:click
│       ├── submit.ts                 # wire:submit
│       ├── keydown.ts                # wire:keydown + key modifiers
│       ├── loading.ts                # wire:loading
│       ├── navigate.ts               # wire:navigate
│       ├── poll.ts                   # wire:poll
│       ├── intersect.ts              # wire:intersect
│       ├── confirm.ts                # wire:confirm
│       ├── transition.ts             # wire:transition
│       ├── init.ts                   # wire:init
│       ├── offline.ts                # wire:offline
│       ├── ignore.ts                 # wire:ignore
│       ├── replace.ts                # wire:replace
│       ├── show.ts                   # wire:show
│       ├── cloak.ts                  # wire:cloak
│       ├── dirty.ts                  # wire:dirty
│       ├── ref.ts                    # wire:ref
│       ├── sort.ts                   # wire:sort
│       ├── stream.ts                 # wire:stream
│       ├── text.ts                   # wire:text
│       ├── current.ts                # wire:current
│       └── bind.ts                   # wire:bind
│
├── providers/
│   └── wire_provider.ts              # AdonisJS ServiceProvider
│
├── commands/
│   ├── make_adowire.ts               # node ace make:adowire
│   └── make_adowire_form.ts          # node ace make:adowire:form
│
├── stubs/
│   ├── component.stub                # Component class stub
│   ├── component_view.stub           # Edge template stub
│   └── form.stub                     # Form class stub
│
├── configure.ts                      # node ace configure adowire
├── index.ts                          # Package main entry point
├── package.json
├── tsconfig.json
├── eslint.config.js
├── PLAN.md                           # This file
└── README.md

4. How It Works (The Lifecycle)

Initial Page Load (GET)

1. AdonisJS route handler renders an Edge template
2. Developer uses @adowire('component-name', props) tag in the template
3. Adowire instantiates the component, calls mount(props), renders it
4. HTML is wrapped with wire:id="<ulid>" and wire:snapshot="<json>"
5. Full page HTML is sent to the browser
6. Browser: adowire.js boots, Alpine.js initialises
7. Each wire:id element becomes a live Alpine-backed component
8. wire:cloak elements become visible, wire:init actions fire

Subsequent Updates (AJAX)

1. User interacts (click, input, submit, poll, intersect, etc.)
2. Client collects pending updates and calls into one request:
   { snapshot, calls: [{ method, params }], updates: { prop: value } }
3. POST /adowire/message
4. Server runs full lifecycle (see Architecture section)
5. Response: { snapshot, effects: { html, redirect, dispatches, js, streams } }
6. Client: morphdom(currentEl, newHtml)
7. Client: process effects sequentially

Snapshot Format

{
  "state": {
    "count": 1,
    "title": "Hello",
    "createdAt": ["2024-01-01T00:00:00.000Z", { "s": "date" }],
    "items": [["a", "b"], { "s": "set" }]
  },
  "memo": {
    "name": "counter",
    "id": "01HXYZ1234567890ABCDEF",
    "children": {},
    "errors": {},
    "locale": "en",
    "path": "/counter",
    "method": "GET"
  },
  "checksum": "hmac-sha256-hex-signature"
}

5. Feature Checklist

🏗️ Core Engine

🎨 Components

HTML-style component tag syntax (src/edge/adowire_html_processor.ts — Edge.js raw preprocessor)

Bug fixed: registerAdowireTags() was missing the edge.processor.process('raw', adowireHtmlProcessor) call in the compiled build (stale build — processor was added to source but package was never recompiled). All <adowire:*> tags rendered as empty until rebuilt.

📋 Properties

✅ Validation (VineJS)

Adowire uses VineJS (@vinejs/vine) as its sole validation engine. VineJS is already a dependency of AdonisJS — zero extra installs for consumers.

📝 Forms (WireForm)

src/concerns/ directory is empty — no WireForm base class or mixins exist yet.

🔁 Lifecycle Hooks

⚡ Actions

📡 Events

🧩 Nesting

🌊 Adowire Directives (HTML Attributes)

Note: All directives use the adowire: prefix (not wire:). The rename from wire:* → adowire:* was applied across the entire codebase: Edge tags, client-side directive handlers, attribute names, and all example templates. The plan below uses the canonical adowire: prefix.

🏷️ TypeScript Decorators

All 16 metadata keys and option interfaces are defined in src/types.ts. src/decorators/ contains @Computed, @Locked, @Validate, @Title, and @Layout (all fully working). 9 of 16 decorators have runtime consumers in component.ts / request_handler.ts (Tier 1). 7 only have the metadata key defined (Tier 2).

🏝️ Islands

@island / @endisland — marks a region for independent re-rendering
@island(name: 'stats') — named island
@island(lazy: true) — defer island render until after page load
@island(defer: true) — render via explicit wire:init trigger
@placeholder / @endplaceholder — shown while lazy island loads
Islands share parent component state and methods
Multiple named islands per component
Islands re-render independently; parent render skips them

🦥 Lazy Loading

@Lazy class decorator — defer component's initial render
Server renders @placeholder content on initial load
Component sends wire:init AJAX call after page loads
@island(lazy: true) for island-level deferred render
Progress / skeleton UI via @placeholder

⏳ Loading States

📎 File Uploads

WithFileUploads mixin applied to component
adowire:model="photo" on <input type="file">
TemporaryUploadedFile class with .store(path), .move(path), .getSize(), .getMime()
VineJS validation: @Validate(vine.file().maxSize(2 * 1024 * 1024).extnames(['jpg','png']))
Multiple file uploads: wire:model="photos" with vine.file().array()
Upload progress events via wire:loading integration
Client-side preview: $wire.photo.temporaryUrl()
Temporary files cleaned up after request

📖 Pagination

WithPagination mixin applied to component
this.page property auto-managed
this.previousPage() / this.nextPage() methods
this.gotoPage(n) method
this.resetPage() method
@Url auto-applied to page property (page in URL)
@adowire/paginate Edge tag for rendering pagination links

🔗 URL Query Parameters

@Url decorator — syncs property to URL query string
@Url({ as: 'q' }) — custom query param name
@Url({ history: 'push' }) — push vs replace history entry
@Url({ except: '' }) — omit default value from URL
Multiple @Url properties per component
Changing URL param triggers component hydrate + update
Back/forward browser navigation triggers component update

🧭 Navigate (SPA Mode)

adowire:navigate on <a> — intercept click, fetch next page, morph full page DOM
adowire:navigate.hover — prefetch page HTML on hover
Browser pushState history management
Scroll-to-top on navigation (configurable)
adowire:current — auto-sets aria-current="page" on matching links
@persist('key') / @endpersist — preserve DOM elements across navigations (audio players, etc.)
Navigation lifecycle browser events:
- adowire:navigate — before navigation starts
- adowire:navigated — after DOM morph completes
Back/forward button support via popstate listener
Page scripts re-evaluated on navigate

🖥️ Teleport

@teleport('#target') / @endteleport — render content into a different DOM node
Useful for modals, toasts, drawers rendered into <body> or #app
Multiple teleport targets per component

🌐 Alpine.js Bridge (`$wire`)

The Alpine.js $wire magic is available inside any x-data scope that is a descendant of an [adowire:id] element. It proxies reads/writes to the component's snapshot state and method calls to commit().

🧪 Testing

No test wrapper/harness exists yet. Unit tests in tests/ exercise internals directly via Japa.

🔧 AdonisJS Integration

🪄 Ace Commands

7 commands implemented. All stubs created. commands/ directory fully wired into the Ace loader.

Command Reference Table

Command	Aliases	Flags	Description
`make:adowire <name>`	—	`--page`/`-p`, `--class`/`-c`, `--view`/`-v`	Scaffold component class + view (default: both)
`adowire:list`	—	`--json`/`-j`	List all registered components in a table or as JSON
`adowire:layout`	—	`--name`/`-n`, `--force`/`-f`	Create `resources/views/layouts/adowire.edge` layout
`adowire:move <from> <to>`	—	—	Move/rename component class + view, updates class name
`adowire:delete <name>`	—	`--force`/`-f`	Delete component class + view (prompts unless `--force`)
`adowire:stubs`	—	`--force`/`-f`	Publish stubs to `stubs/vendor/adowire/` for customisation
`node ace configure adowire`	—	—	Publish config, register provider + commands in `adonisrc.ts`

🔒 Security

HMAC-SHA256 snapshot checksum — createHmac('sha256', secret) in snapshot.ts, timingSafeEqual verification
@Locked properties — decorator in src/decorators/locked.ts fully implemented; runtime guard in applyUpdates throws LockedPropertyException
$isCallable() guard — blocks lifecycle hooks, $-prefixed, _-prefixed, and ReservedMethodNames set (20 names including reset, fill, validate, etc.)
MethodNotCallableException with clear error message when client attempts to call reserved/private methods
Action parameters treated as untrusted user input — documentation/guidance only
CSRF protection — AdonisJS CSRF middleware; token injected via @adowireScripts meta tag, sent as X-CSRF-TOKEN header
Protected/private class members never included in snapshot — $getPublicState() filters $/_ prefixed keys
CSP nonce support for inline scripts injected by @!adowireScripts()

🧬 DOM Morphing

morphdom integration — surgical DOM diffing and patching (morph.ts wraps morphdom)
adowire:key attribute used as morph key for stable element identity (getNodeKey callback in morph.ts)
Alpine.js state preserved during morph (no __x_dataStack / _x_dataStack preservation logic)
adowire:ignore — skip morphing subtree entirely (onBeforeElUpdated + onBeforeNodeDiscarded)
adowire:ignore.self — morph children but not root element (not distinguished from adowire:ignore)
adowire:replace — replace children wholesale instead of morphing

Server-side morph marker injection around @if / @each Edge blocks:

<!--[if BLOCK]> <![endif]-->
...conditional content...
<!--[if ENDBLOCK]> <![endif]-->

Look-ahead algorithm in morphdom config — detects insertions vs replacements
injectMorphMarkers: false config option to disable markers (config key accepted but no injection code)

🌍 Global JavaScript API

Adowire.init() — boot all components found on the page (called automatically on DOMContentLoaded)
Adowire.on('event', fn) — global Livewire-style event listener, returns cleanup()
Adowire.find(id) — find component instance by adowire:id attribute value
Adowire.getByName('counter') — find first component by registered name
Adowire.all() — array of all active component instances on the page (components Map exists but no .all() helper)
Adowire.navigate(url) — programmatic SPA navigation
Adowire.hook('request', fn) — intercept all requests
Adowire.hook('response', fn) — intercept all responses
Browser events dispatched on document:
- adowire:init — after all components boot
- adowire:request — before each AJAX request
- adowire:response — after each AJAX response
- adowire:error — on AJAX or server error
- adowire:morph — before morphdom runs
- adowire:morphed — after morphdom completes
- adowire:navigate — before SPA navigation
- adowire:navigated — after SPA navigation DOM update

6. Build Phases

Phase 1 — Core Engine 🏗️

Goal: A counter with wire:click="increment" works end-to-end.

Milestone: Counter increments without page reload. ✅

Phase 2 — Properties & Model 📋

Goal: A todos list with wire:model live updates works.

client/directives/model.ts — deferred binding (submit-time serialisation)
client/directives/loading.ts — show/hide, class, attr toggling while in-flight
client/directives/cloak.ts
client/directives/dirty.ts
src/decorators/locked.ts
src/decorators/computed.ts
fill(), reset(), pull(), only(), all() on WireComponent

Milestone: Model-submit form with deferred binding works. Model live modifiers (live, blur, debounce, throttle) implemented. Loading states work. Bulk state helpers implemented. Cloak, dirty, @Locked, @Computed decorators implemented. ✅

Phase 3 — Validation (VineJS) ✅

Goal: Create-post form with real-time validation and @error display works.

src/validator.ts — WireValidator class with validateProperty() and validateProperties(), lazy dynamic VineJS import
src/wire_exception.ts — ValidationException, LockedPropertyException, MethodNotCallableException, RenderException
src/decorators/validate.ts — @Validate(rule, opts?) with message, as, onUpdate options
src/edge/tags/error.ts — @error('field') / @enderror block tag exposing message and messages
validate(), addError(), resetValidation() on component — validate() uses WireValidator, clears passing props, throws ValidationException on failure
validateUsing(compiledValidator) on component — runs a pre-compiled vine.compile(schema) validator against full public state; assigns coerced values back to properties; catches native VineJS errors and converts to ValidationException
withValidator() on component — programmatic validator attachment (not yet implemented)
$errors client-side object (has, first, get, all, clear) — client-side structured error API not yet built
VineJS E_VALIDATION_ERROR caught → errors in response → re-render (request handler maybeValidateOnUpdate runs per-property validation on update)

Milestone: Form with @Validate(vine.string().minLength(3)), real-time errors, @error tags. ✅

Phase 4 — Forms 📝

Goal: Reusable WireForm objects, used across create + edit pages.

src/form.ts
Form as typed property: public PostForm $form
wire:model="form.title" nested binding
@error('form.field') nested errors
node ace make:adowire:form PostForm

Milestone: PostForm reusable across CreatePost and EditPost. ✅

Phase 5 — Events & Nesting 📡🧩

Goal: Parent/child communication, @On, @Reactive, slots all work.

dispatch() and all variants
src/decorators/on.ts
src/edge/tags/wire_component.ts (fully working with children)
Child independent re-render logic
src/decorators/reactive.ts
src/decorators/modelable.ts
Slots (default + named)
$attributes forwarding
$parent.method() template support

Milestone: Todos parent + TodoItem child with $parent, events, reactive count. ✅

Phase 6 — Decorators & Directives 🏷️

Goal: Full directive set, URL sync, polling, intersection, session, etc.

Milestone (partial): @Title, @Layout, poll, ignore directives working. Remaining decorators & directives pending.

Phase 7 — Islands & Lazy 🏝️🦥

src/edge/tags/island.ts
src/edge/tags/placeholder.ts
Island independent re-rendering
src/decorators/lazy.ts

Milestone: Islands and lazy-loaded components work. ✅

Phase 8 — Navigate & Teleport 🧭🖥️

client/directives/navigate.ts
SPA page morphing + history management
wire:navigate.hover prefetch
src/edge/tags/persist.ts
src/edge/tags/teleport.ts
Navigation browser events

Milestone: Full app SPA navigation with back/forward, persisted elements. ✅

Phase 9 — File Uploads & Pagination 📎📖

src/concerns/with_file_uploads.ts
TemporaryUploadedFile + VineJS file schema integration
src/concerns/with_pagination.ts
Pagination Edge component
client/directives/sort.ts

Milestone: File upload with progress, pagination with URL sync, drag-drop sort. ✅

Phase 10 — Streaming 🌊

$stream(name, content, replace?) on WireComponent — with $streamWriter callback for real-time push
Client-side stream handling in component.ts _applyStreamChunk() + _applyResponse()
SSE streaming over text/event-stream response — request handler detects Accept: text/event-stream, opens SSE connection, pushes event: stream per chunk, sends event: response at end
Client Connection.requestStreaming() — parses SSE ReadableStream, dispatches chunks in real-time
Automatic SSE mode: client sends Accept: text/event-stream when action calls are present; server falls back to JSON for non-streaming actions

Milestone: AI/LLM streaming text into wire:stream element — words appear in real-time. ✅

Phase 11 — Testing & CLI 🧪🪄

CLI — ✅ Complete

Testing — ⏳ Pending

src/testing/wire_test.ts
All assert* methods
commands/make_adowire_form.ts (blocked on WireForm)

Milestone: node ace make:adowire scaffolds correctly ✅ — full Japa test suite pending.

Phase 12 — Polish & Publish 📦

src/synthesizers/ — Date, Set, Map synthesizers (with custom Synthesizer interface)
Adowire.synthesizer(impl) — user-extensible
README.md — full developer documentation
All CI checks passing (lint, typecheck, tests)
npm publish with provenance

Milestone: v1.0.0 published to npm. ✅

New: Dev-Mode Template Safety 🛡️

Added outside original phases — provides runtime + compile-time type safety for Edge templates.

New: Example Demo Pages 🎓

Working example components in adowire-test/ demo app exercising each directive.

7. API Design (Developer-Facing)

Component Class

// app/adowire/counter.ts
import { WireComponent } from 'adowire'
import { Computed, Locked, Validate, On } from 'adowire/decorators'
import vine from '@vinejs/vine'

export default class Counter extends WireComponent {
  count = 0

  @Locked()
  userId!: number

  @Validate(vine.number().min(1).max(100))
  limit = 10

  async mount({ initialCount = 0 }: { initialCount?: number }) {
    this.count = initialCount
    this.userId = this.$ctx.auth.user!.id
  }

  increment() {
    this.count++
  }

  decrement() {
    if (this.count > 0) this.count--
  }

  @Computed()
  get doubled() {
    return this.count * 2
  }

  @On('count-reset')
  resetCount() {
    this.count = 0
  }
}

Edge Template

{{-- resources/views/adowire/counter.edge --}}
<div>
  <h1>
    Count: {{ count }}
  </h1>
  <h2>
    Doubled: {{ await $this.doubled }}
  </h2>

  <button wire:click="decrement">-</button>
  <button wire:click="increment">+</button>
  <button wire:click="$refresh">Refresh</button>
  <button wire:click="$toggle('showDetails')">Toggle</button>

  @if(showDetails)
    <p wire:transition>
      Details here
    </p>
  @end
  
  <span wire:loading>Updating...</span>
</div>

Layout Template

{{-- resources/views/layouts/adowire.edge --}}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>
      My App
    </title>
    @!wireStyles()
  </head>
  <body>
    {{{ await $slots.main() }}}
    @!wireScripts()
  </body>
</html>

Form Object

// app/adowire/forms/post_form.ts
import { WireForm } from 'adowire'
import { Validate } from 'adowire/decorators'
import vine from '@vinejs/vine'

export default class PostForm extends WireForm {
  @Validate(vine.string().minLength(3).maxLength(255))
  title = ''

  @Validate(vine.string().minLength(10))
  content = ''

  async store() {
    await this.validate()
    // save to DB ...
    this.reset()
  }

  async update(post: Post) {
    await this.validate()
    await post.merge(this.only(['title', 'content'])).save()
    this.reset()
  }
}

Component Using Form

// app/adowire/posts/create.ts
import { WireComponent } from 'adowire'
import { Layout, Title } from 'adowire/decorators'
import PostForm from '#wire/forms/post_form'

@Title('Create Post')
@Layout('layouts/adowire')
export default class CreatePost extends WireComponent {
  declare form: PostForm

  async mount() {
    this.form = new PostForm(this)
  }

  async save() {
    await this.form.store()
    this.$redirect('/posts')
  }
}

Route Registration

// start/routes.ts
import router from '@adonisjs/core/services/router'

// Regular page — component embedded inside a view
router.get('/dashboard', async ({ view }) => {
  return view.render('pages/dashboard')
})

// Wire page routes — component IS the page
router.wire('/posts/create', 'posts.create')
router.wire('/posts/:id/edit', 'posts.edit')

8. VineJS Validation Design

How `@Validate` Works

The @Validate decorator accepts a VineJS schema type directly — not a string rule like 'required|min:3'. This is the key difference from Livewire's PHP attribute approach.

import vine from '@vinejs/vine'
import { Validate } from 'adowire/decorators'

// Simple rule
@Validate(vine.string().minLength(3))
title = ''

// With options
@Validate(vine.string().email(), {
  message: 'Please enter a valid email address',
  as: 'email address',   // replaces field name in default messages
  onUpdate: true,        // default: validate on every property update
})
email = ''

// Stacked rules (multiple decorators)
@Validate(vine.string().minLength(3), { message: 'Title is too short' })
@Validate(vine.string().maxLength(255), { message: 'Title is too long' })
title = ''

How `validate()` Works Internally

When this.validate() is called, adowire:

Collects all @Validate decorated properties and their VineJS schemas
Builds a vine.object({ title: vine.string()..., content: vine.string()... })
Pre-compiles it with vine.create(schema)
Applies the SimpleMessagesProvider with any custom messages from options
Calls validator.validate(this.all())
On E_VALIDATION_ERROR: populates this.$errors from error.messages, throws ValidationException
On success: returns validated+typed data

Using `rules()` for Complex VineJS Scenarios

For scenarios requiring VineJS's full power (unions, conditional groups, cross-field validation):

export default class RegisterUser extends WireComponent {
  username = ''
  email = ''
  password = ''
  passwordConfirmation = ''
  isBusinessAccount = false
  companyName = ''

  // Override rules() for complex VineJS schemas
  protected rules() {
    const base = vine.object({
      username: vine.string().minLength(3).alphaNumeric(),
      email: vine.string().email().normalizeEmail(),
      password: vine.string().minLength(8).confirmed(),
    })

    // Conditional group — companyName required for business accounts
    const businessGroup = vine.group([
      vine.group.if((data) => vine.helpers.isTrue(data.isBusinessAccount), {
        isBusinessAccount: vine.literal(true),
        companyName: vine.string().minLength(2),
      }),
      vine.group.else({
        isBusinessAccount: vine.literal(false),
      }),
    ])

    return base.merge(businessGroup)
  }

  protected messages() {
    return {
      'username.minLength': 'Username must be at least {{ min }} characters',
      'email.required': 'Please enter your email address',
      'password.confirmed': 'Passwords do not match',
      'companyName.required': 'Company name is required for business accounts',
    }
  }

  protected validationAttributes() {
    return {
      passwordConfirmation: 'password confirmation',
      companyName: 'company name',
    }
  }

  async register() {
    await this.validate()
    // ...
  }
}

Real-Time Validation

When wire:model.live or wire:model.blur is used, adowire runs the @Validate schema for only the updated property on each server round-trip:

<input type="text" wire:model.live.blur="title" />
@error('title')
  <p class="text-red-500">
    {{ message }}
  </p>
@enderror

@Validate(vine.string().minLength(3).maxLength(255))
title = ''

Adowire validates title alone (not the whole form) on every blur event. The full validate() is still called on submit.

`$errors` Client-Side (via Alpine `$wire`)

<input wire:model="email" type="email" />
<div wire:show="$wire.$errors.has('email')" class="text-red-500">
  <span wire:text="$wire.$errors.first('email')"></span>
</div>

9. Edge.js Template API

Tag	Description
`@!wireStyles()`	Inject adowire CSS (placeholder, future use)
`@!wireScripts()`	Inject Alpine.js + adowire `wire.js` client bundle
`@adowire('name', props?)`	Render a nested wire component
`@adowire($dynamicName, props?)`	Dynamic component rendering
`@adowire.slot('name')`	Named slot content passed to child
`@island` / `@endisland`	Independent re-render region
`@island(name: 'x', lazy: true)`	Named + lazy island
`@placeholder` / `@endplaceholder`	Shown while lazy component/island loads
`@persist('key')` / `@endpersist`	Preserve element across SPA navigations
`@teleport('#target')` / `@endteleport`	Render into different DOM node
`@error('field')` / `@enderror`	Show first validation error for field

Globals Available in Wire Templates

Variable	Type	Description
`$this`	Component instance	Access computed properties
`$errors`	ErrorBag	Server-side validation errors
`$slots`	SlotsBag	Named slots from parent
`$attributes`	AttributesBag	HTML attributes forwarded from parent
`$wire`	AlpineBridge	Client-side wire bridge (for inline Alpine)

10. Client-Side Directives

Directive	Key Modifiers	Description
`wire:model`	`.live`, `.blur`, `.debounce.Xms`, `.throttle.Xms`	Two-way binding
`wire:click`	`.async`, `.renderless`, `.preserve-scroll` + event modifiers	Server action
`wire:submit`	event modifiers	Form submit interception
`wire:keydown`	key modifiers + event modifiers	Keyboard action
`wire:loading`	`.class`, `.attr`, `.remove`, `.delay`, `.delay.Xms`	Loading state
`wire:target`	—	Scope `wire:loading` to specific action/prop
`wire:navigate`	`.hover`	SPA navigation
`wire:current`	—	Active link marker
`wire:poll`	`.Xs`, `.visible`, `.keep-alive`	Auto-refresh
`wire:intersect`	`.once`, `.enter`, `.leave`	Viewport trigger
`wire:init`	—	On component client-boot
`wire:confirm`	`.prompt`	Confirmation dialog
`wire:transition`	`.in`, `.out`, `.duration.Xms`	CSS transitions
`wire:offline`	—	Show when offline
`wire:dirty`	`.class`, `.class.remove`	Dirty state
`wire:cloak`	—	Hide until component boots
`wire:ignore`	`.self`	Prevent morphdom touching element
`wire:replace`	—	Replace children wholesale
`wire:ref`	—	Named element reference
`wire:show`	—	Reactive CSS visibility
`wire:text`	—	Reactive text node
`wire:bind:attr`	—	Reactive attribute
`wire:sort`	`.item`, `.handle`	Drag-drop sorting
`wire:stream`	`.replace`	Streaming text target

11. TypeScript Decorators

Decorator	Target	Description
`@Computed()`	Method (getter)	Memoize result per request; accessible as `$this.prop` in Edge
`@Locked()`	Property	Block all client-side mutation attempts
`@Validate(vineSchema, opts?)`	Property	VineJS schema rule on property
`@Url(opts?)`	Property	Sync to URL query parameter
`@On('event')`	Method	Listen for dispatched component event
`@On('event.{prop.id}')`	Method	Dynamic event name with component state
`@Reactive()`	Property	Re-sync from parent on every parent update
`@Modelable()`	Property	Expose for parent `wire:model` binding
`@Lazy(opts?)`	Class	Defer initial render until after page load
`@Session(opts?)`	Property	Persist value in AdonisJS session store
`@Async()`	Method	Fire-and-forget; does not block request queue
`@Renderless()`	Method	Action executes but skips re-render
`@Defer()`	Property	Batch update until next explicit action
`@Isolate()`	Method	Prevents dispatched events from bubbling
`@Json()`	Method	Returns JSON directly for JS consumption (skips re-render)
`@Title('text')`	Class	Sets `<title>` tag for page components
`@Layout('view', opts?)`	Class	Wraps page component in a layout view

12. Security Model

Threat	Mitigation
Snapshot state tampering	HMAC-SHA256 on every snapshot; verified before hydration
Injecting values into `@Locked` properties	Server throws `E_LOCKED_PROPERTY` before hydration
Calling private/protected methods	`$isCallable()` guard — only callable public methods
Calling lifecycle hooks directly	All hook names explicitly blocked in `$isCallable()`
Action parameter forgery	Documented: treat as untrusted input, always validate/authorize
CSRF attacks	AdonisJS CSRF middleware; token sent in `X-CSRF-TOKEN` header on all AJAX
Sensitive data leakage to client	Protected/private properties excluded from snapshot
Type coercion attacks on properties	VineJS schema types enforce strict casting

13. Testing Strategy

Unit Tests (Japa)

SnapshotManager — dehydrate/hydrate round-trips for all types
HMAC checksum signing and tamper detection
ComponentRegistry — name resolution, namespace handling
Decorator metadata — @Validate, @Locked, @On, @Computed etc.
WireValidator — VineJS schema composition from @Validate decorators
morph_markers — correct injection around @if/@each blocks

Integration Tests (Japa)

Full request lifecycle: mount → dehydrate → AJAX → hydrate → action → dehydrate → render
VineJS E_VALIDATION_ERROR caught and re-rendered with errors
Events dispatched and received by @On listeners
@Locked properties throw on mutation
Redirect effects in response
Nested component rendering and independence
@Reactive prop re-sync

E2E Tests (Japa + Playwright — Phase 12)

wire:model.live two-way binding in browser
wire:click action call and DOM update
wire:submit with VineJS validation errors shown
wire:loading visibility during request
DOM morphing correctness with wire:key
SPA navigation with wire:navigate

14. Ace Commands Reference

Status: ✅ Implemented — 7 commands, all tested in adowire-test.

Full Command Table

Command	Short flags	Description
`make:adowire <name>`	`--page`/`-p` `--class`/`-c` `--view`/`-v`	Scaffold component class + Edge view. Default: both.
`adowire:list`	`--json`/`-j`	Pretty-print table of all registered components (name, view, class path).
`adowire:layout`	`--name`/`-n` `--force`/`-f`	Create `resources/views/layouts/adowire.edge` (or custom name).
`adowire:move <from> <to>`	—	Rename/move class + view; rewrites the class declaration to match the new name.
`adowire:delete <name>`	`--force`/`-f`	Delete class + view with confirmation prompt (skip with `--force`).
`adowire:stubs`	`--force`/`-f`	Publish all stubs to `stubs/vendor/adowire/` for customisation. Skips existing unless `--force`.
`configure adowire`	—	Publish `config/adowire.ts`, register provider + commands in `adonisrc.ts`, create scaffold dirs.

`node ace make:adowire <name>`

Scaffolds a wire component class and its Edge.js view template.

# Basic component — creates BOTH class and view (default)
node ace make:adowire counter
# → app/adowire/counter.ts
# → resources/views/adowire/counter.edge

# Nested path
node ace make:adowire posts/create
# → app/adowire/posts/create.ts
# → resources/views/adowire/posts/create.edge

# Page component (adds @Layout + @Title decorators)
node ace make:adowire pages/dashboard --page
# → app/adowire/pages/dashboard.ts   ← with @Title('Dashboard') @Layout('layouts/adowire')
# → resources/views/adowire/pages/dashboard.edge

# Class only — no view
node ace make:adowire widgets/badge --class
# → app/adowire/widgets/badge.ts

# View only — no class
node ace make:adowire widgets/badge --view
# → resources/views/adowire/widgets/badge.edge

# --class and --view together = same as default (both)
node ace make:adowire widgets/badge --class --view
# → app/adowire/widgets/badge.ts
# → resources/views/adowire/widgets/badge.edge

Flag	Alias	Description
`--page`	`-p`	Page variant: adds `@Title` and `@Layout('layouts/adowire')` decorators to the class
`--class`	`-c`	Generate class file only; skip the Edge view
`--view`	`-v`	Generate Edge view only; skip the class file

Note: AdonisJS generators singularise names (stats → stat, posts → post). This matches the same behaviour as make:model.

`node ace adowire:list`

Lists all auto-discovered and manually registered components.

node ace adowire:list
# ┌─────────────────┬─────────────────────────────┬─────────────────────────────────────────┐
# │ Name            │ View                        │ Class Path                              │
# ├─────────────────┼─────────────────────────────┼─────────────────────────────────────────┤
# │ counter         │ adowire/counter             │ .../app/adowire/counter.ts              │
# │ posts.create    │ adowire/posts/create        │ .../app/adowire/posts/create.ts         │
# │ pages.dashboard │ adowire/pages/dashboard     │ .../app/adowire/pages/dashboard.ts      │
# └─────────────────┴─────────────────────────────┴─────────────────────────────────────────┘
#   Total: 3 component(s)

node ace adowire:list --json
# [{ "name": "counter", "classPath": "...", "viewName": "adowire/counter" }, ...]

Flag	Alias	Description
`--json`	`-j`	Output component list as a JSON array instead of a table

`node ace adowire:layout`

Creates the default Adowire layout template. Writes the file directly (not through tempura) so Edge.js expressions like {{ $title }} and {{{ $body }}} are preserved verbatim.

# Create resources/views/layouts/adowire.edge  (default name)
node ace adowire:layout

# Create with a custom name
node ace adowire:layout --name app

# Overwrite if already exists
node ace adowire:layout --force

Generated output (resources/views/layouts/adowire.edge):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>{{ $title ?? 'App' }}</title>
  @adowireStyles
</head>
<body>
  {{{ $body }}}
  @adowireScripts
</body>
</html>

Flag	Alias	Description
`--name`	`-n`	Layout filename without `.edge` extension (default: `adowire`)
`--force`	`-f`	Overwrite the file if it already exists

`node ace adowire:move <from> <to>`

Renames or moves a component. Moves both the class file and the view file, and rewrites the class declaration inside the class file to match the new name.

# Rename a flat component
node ace adowire:move counter widgets/counter
# DONE: move .../app/adowire/counter.ts → .../app/adowire/widgets/counter.ts
# DONE: move .../resources/views/adowire/counter.edge → .../resources/views/adowire/widgets/counter.edge
# (class renamed Counter → Counter — same in this case)

# Rename across paths, class name changes
node ace adowire:move posts/create forms/post_create
# class PostCreate → class PostCreate  (etc.)

Files that don't exist are skipped with a warning rather than causing an error.

`node ace adowire:delete <name>`

Deletes a component class and its view. Prompts for confirmation unless --force is given.

# With confirmation prompt
node ace adowire:delete counter
# ? Delete component "counter" and its view? This cannot be undone. (y/N)

# Skip prompt
node ace adowire:delete counter --force
# DONE: delete .../app/adowire/counter.ts
# DONE: delete .../resources/views/adowire/counter.edge

Flag	Alias	Description
`--force`	`-f`	Skip the confirmation prompt

`node ace adowire:stubs`

Publishes the package's built-in stubs to stubs/vendor/adowire/ so developers can customise the scaffolding templates. AdonisJS automatically prefers stubs found in the app's own stubs/ directory over package defaults.

# Publish (skips files that already exist)
node ace adowire:stubs
# DONE: create stubs/vendor/adowire/make/component.stub
# DONE: create stubs/vendor/adowire/make/page.stub
# DONE: create stubs/vendor/adowire/make/view.stub
# DONE: create stubs/vendor/adowire/make/layout.stub
# DONE: create stubs/vendor/adowire/config/adowire.stub

# Overwrite existing stubs
node ace adowire:stubs --force

Flag	Alias	Description
`--force`	`-f`	Overwrite stubs that already exist in the destination

Published stubs:

Stub file	Used by
`make/component.stub`	`make:adowire` (basic class)
`make/page.stub`	`make:adowire --page`
`make/view.stub`	`make:adowire` (Edge template)
`make/layout.stub`	(reference only — `adowire:layout` writes directly)
`config/adowire.stub`	`node ace configure adowire`

`node ace configure adowire`

Run once after installing the package. Uses AdonisJS codemods to:

Publish config/adowire.ts (via stubs/config/adowire.stub)
Register adowire/wire_provider in adonisrc.ts providers
Register adowire/commands in adonisrc.ts commands
Create app/adowire/ and resources/views/adowire/ scaffold directories

node ace configure adowire
# ✔ Adowire configured successfully!
#
#   Next steps:
#     node ace make:adowire counter             # basic component
#     node ace make:adowire dashboard --page    # page component
#     node ace adowire:list                     # list all components

`node ace make:adowire:form <name>` (planned)

⚠️ Not yet implemented — blocked on WireForm (Phase 4).

Will scaffold a WireForm class alongside or independently of a component.

node ace make:adowire:form PostForm
# → app/adowire/forms/post_form.ts

15. Package Publishing

Status: Publishable as alpha 0.x.x. Not ready for stable 1.0.0 yet.

Subpath Exports (actual `package.json`)

{
  "exports": {
    ".": "./build/index.js",
    "./types": "./build/src/types.js",
    "./wire_provider": "./build/providers/wire_provider.js",
    "./client": "./build/adowire.js",
    "./commands": "./build/commands/main.js"
  }
}

Subpath	Resolves to	Purpose
`.`	`build/index.js`	Main entry — exports `WireComponent`, decorators, types, Edge plugin, etc.
`./types`	`build/src/types.js`	`AdowireConfig`, `WireSnapshot`, `ComponentDefinition`, etc.
`./wire_provider`	`build/providers/wire_provider.js`	AdonisJS service provider (registered in `adonisrc.ts`)
`./client`	`build/adowire.js`	Browser-side IIFE bundle (morphdom, directives, connection)
`./commands`	`build/commands/main.js`	Ace loader — `getMetaData()` / `getCommand()` for all 7 commands

Planned (not yet implemented):

Subpath	Purpose	Blocked on
`./decorators`	Standalone decorator imports	—
`./concerns`	Reusable trait/concern mixins	Phase 5
`./testing`	`WireTest` test utilities	Phase 11 testing

What Gets Published

build/
  index.js + index.d.ts            ← main entry (server-side exports)
  configure.js + configure.d.ts    ← node ace configure adowire
  adowire.js                       ← client-side IIFE bundle (27 KB)
  chunk-*.js                       ← shared chunk (reflect-metadata re-export)
  wire_provider-*.js               ← provider chunk (95 KB — component registry, snapshot, Edge plugin, request handler)
  dev_proxy-*.js                   ← dev-mode template proxy chunk
  stubs/
    main.js + main.d.ts            ← stubsRoot = import.meta.dirname
    make/component.stub             ← basic WireComponent class
    make/page.stub                  ← page component (@Layout + @Title)
    make/view.stub                  ← Edge.js template with {{-- comment --}}
    make/layout.stub                ← layout reference (adowire:layout writes directly)
    config/adowire.stub             ← config/adowire.ts published by configure hook
  commands/
    main.js + main.d.ts            ← Ace loader (getMetaData / getCommand + all 7 commands bundled)
    commands.json                   ← command metadata manifest
    *.d.ts                          ← declaration files for each command
  providers/
    wire_provider.js + .d.ts        ← re-export entry for the provider
  src/
    *.d.ts                          ← all server-side type declarations
  client/
    *.d.ts                          ← client-side type declarations

Excluded from the tarball (via "files" in package.json):

build/bin/ — test runner
build/tests/ — test spec declarations

Tarball size: ~86 KB compressed, ~289 KB unpacked.

How to Publish

# 1. Log in to npm (one-time)
npm login

# 2. Publish via release-it (recommended — builds, tags, publishes, creates GitHub release)
npx release-it          # prompts for version bump
npx release-it patch    # 0.1.0 → 0.1.1
npx release-it minor    # 0.1.0 → 0.2.0

# Or manually:
npm run build
npm publish

Do consumers need to reinstall after each build?

Symlinked dev (file:../adowire): No. The symlink always points at the live build/ directory. Just npm run compile in the adowire folder and restart the dev server.
Published package (npm install adowire): Yes — consumers run npm update adowire to get the new version.

Publishability Checklist

Item	Status
`package.json` name, version, description	✅
`package.json` author, repository, bugs, homepage	✅
`package.json` license (MIT)	✅
`package.json` exports (5 subpaths)	✅
`package.json` files (excludes tests/bin)	✅
`package.json` engines (`>=24.0.0`)	✅
`package.json` peerDependencies (`@adonisjs/core ^7`, `edge.js ^6`)	✅
`publishConfig` (public, provenance)	✅
`release-it` config (git tags, GitHub release, conventional changelog)	✅
`prepublishOnly` script (auto-builds)	✅
Build output clean (no test/bin leaks)	✅
Type declarations (`.d.ts`) generated	✅
README.md	⚠️ Needs alpha warning + basic usage docs
CI (GitHub Actions)	❌ Not set up yet
Test suite	❌ No automated tests (testing harness is Phase 11)

Feature Completion Summary (for README)

Area	Status	Completion
Core Engine (snapshot, hydration, morphing)	✅ Ship-ready	100%
Properties & Model binding	✅ Ship-ready	90%
Lifecycle Hooks	✅ Ship-ready	92%
Streaming (`$stream`, `adowire:stream`)	✅ Ship-ready	100%
CLI / Ace Commands (7 commands)	✅ Ship-ready	94%
Dev-Mode Template Safety	✅ Ship-ready	100%
AdonisJS Integration (provider, Edge, router.adowire)	🟡 Partial	54%
Validation (VineJS)	🟡 Partial	43%
Directives (HTML attributes)	🟡 Partial	38%
Actions	🟡 Partial	52%
Decorators	🟡 Partial	33%
Security (HMAC, CSRF, callable guard)	🟡 Partial	75%
Forms (WireForm)	❌ Not started	0%
Events & Nesting	❌ Not started	0%
Islands & Lazy Loading	❌ Not started	0%
File Uploads	❌ Not started	0%
Pagination	❌ Not started	0%
URL Query Parameters	❌ Not started	0%
Navigate (SPA Mode)	❌ Not started	0%
Teleport	❌ Not started	0%
Testing Harness	❌ Not started	0%

Versioning

Semantic Versioning (semver)
Conventional commits → auto-changelog via @release-it/conventional-changelog
Pre-release: 0.x.x during active development
Stable 1.0.0 after Phases 1–9 features complete and tested (Forms, Events, Nesting, Directives, Islands, Navigate, File Uploads, Pagination)
CI: GitHub Actions — lint + typecheck + tests on Ubuntu + Windows, Node.js 24+

Adowire Build Plan v1.1

FilesExpand file tree

PLAN.md

Latest commit

History