# Source Reconciliation and Claim Audit

**Audit date:** 2026-07-19  
**Source corpus:** four uploaded Markdown guides, 3,274 lines total  
**Output:** twelve standalone onboarding documents

## Source inventory

| Source | Lines | Primary angle |
| --- | ---: | --- |
| `alpine-and-htmx-as-coequals(1).md` | 908 | normative architecture, ownership, component contracts |
| `alpine-for-htmx-developers(1).md` | 790 | Alpine concepts from an htmx-first viewpoint |
| `alpine-htmx-superpowers(1).md` | 771 | advanced combined capabilities |
| `htmx-for-alpine-developers(1).md` | 805 | htmx concepts from an Alpine-first viewpoint |

## Reconciliation method

Every source statement was treated as one of three types:

1. **Library behavior** — checked against current official Alpine.js or htmx documentation.
2. **Web-platform behavior** — checked for consistency with native forms, links, URLs, events, focus, and DOM lifecycle.
3. **Recommended architecture/team convention** — cross-checked across all four source guides for contradiction and rewritten as an explicit convention rather than an official library guarantee.

The four guides strongly agree on the central doctrine:

- Alpine owns temporary browser-local interaction.
- htmx owns HTTP interaction and targeted server HTML installation.
- the server owns durable, shared, permission-sensitive truth.
- native controls bridge local reactivity and submission.
- URLs own navigable state.
- stable Alpine shells should surround smaller replaceable htmx interiors when local state must survive.
- replacing an Alpine root is correct when local state should reset.
- semantic browser events connect independently owned regions.
- OOB swaps should update related authoritative server projections.
- preservation and morphing are exceptional.
- accessibility, security, error behavior, history, and cleanup are architectural concerns.

## Official version verification

Verified against official project sources on 2026-07-19:

- Alpine.js latest GitHub release: **3.15.12**.
- htmx latest stable documentation: **2.0.10 / 2.x**.
- htmx 4 documentation: **4.0.0-beta5**, prerelease.
- htmx 4 migration documentation confirms changed event names, explicit inheritance by default, changed `4xx`/`5xx` swapping defaults, disable-attribute changes, and extension changes.

The package therefore uses Alpine 3.x and htmx 2.x syntax and places a migration warning in every lesson.

## Qualifications and corrections applied

### 1. `hx-disabled-elt` descendant selection

Source examples sometimes use:

```html
hx-disabled-elt="find button, find input, find select"
```

In htmx 2, `find <selector>` resolves a matching descendant; it should not be taught as “disable every descendant of that element type.” The package uses a disabled `<fieldset>` plus explicit buttons or explicit IDs when broad form disabling is required.

### 2. Trigger `from:` scope

A source active-search example uses broad selectors such as `from:input` and `from:select`. htmx evaluates `from:` selectors according to its trigger rules and the result may be page-wide or resolved only at initialization. The package prefers exact IDs, attributes on the triggering controls, or an intentionally global `window` event.

### 3. Modal inertness

A source uses a simplified example equivalent to making `document.body` inert when a modal is open. If the modal is inside `body`, that can disable the modal itself. The package omits this shortcut and uses native `<dialog>` or a tested focus/inert implementation.

### 4. htmx 2 validation status codes

The sources correctly warn that htmx 2 does not swap `4xx`/`5xx` by default. The package turns this into an explicit project decision: return expected validation HTML with a swap-eligible status such as `200`, or configure and test error swapping deliberately.

### 5. htmx 4 incompatibility

The source baseline says htmx 4 is prerelease and behavior differs. Current official documentation confirms that. The package avoids htmx 4 event syntax and marks every lifecycle example as htmx 2-specific.

### 6. Alpine-created htmx markup

The sources correctly state that markup created later by Alpine may require `htmx.process(newRegion)`. The package emphasizes processing only the newly created subtree after `$nextTick`, not the whole document.

### 7. htmx-created Alpine markup

Alpine 3 observes DOM additions and normally initializes Alpine markup inserted by htmx as fresh components. The package treats this as a lifecycle behavior that must be verified in browser integration tests, especially when morphing or compatibility extensions are introduced. It never calls `Alpine.start()` after swaps.

### 8. Cleanup

The sources correctly pair Alpine `init()` with `destroy()` and recommend htmx cleanup events for third-party widgets. The package adds explicit leak testing for timers, global listeners, observers, and widget instances.

### 9. Response-trigger events

The sources correctly use `HX-Trigger`, `HX-Trigger-After-Swap`, and `HX-Trigger-After-Settle`. The package adds two cautions:

- event payloads are not automatically request parameters;
- response trigger headers are not processed on ordinary redirect responses.

### 10. Delete responses

The sources use `hx-swap="delete"` appropriately. The package notes the htmx 2 behavior that a `204` performs no swap, so a project relying on delete swapping must use a tested successful response policy.

### 11. Preservation and morphing

The sources consistently recommend better boundaries first. The package adds official `hx-preserve` caveats: stable IDs are required, certain elements do not preserve perfectly, and history/OOB relocation must be tested.

### 12. CSP

The source security doctrine is correct but general. The package explicitly distinguishes Alpine’s normal build from its CSP build and warns that the CSP build has syntax limitations. It also discourages inline scripting when a strict CSP is a goal.

### 13. Progressive enhancement and cache variation

The sources correctly require direct routes. The package makes cache variation explicit when the same URL returns full-page and fragment representations, commonly with `Vary: HX-Request` or a framework equivalent.

### 14. “Co-equal” is a convention

Official Alpine and htmx documentation describe capabilities, not the exact constitutional rule “one authoritative owner per state value and one writer per DOM boundary.” That rule is a reconciled architectural convention from the source corpus. It is labeled as such and used consistently throughout the package.

## Cross-document consistency map

| Topic | Co-equals | Alpine for htmx | Superpowers | htmx for Alpine |
| --- | :---: | :---: | :---: | :---: |
| server authority | ✓ | ✓ | ✓ | ✓ |
| local Alpine state | ✓ | ✓ | ✓ | ✓ |
| target/lifecycle boundary | ✓ | ✓ | ✓ | ✓ |
| native control bridge | ✓ | ✓ | ✓ | ✓ |
| request-state ownership | ✓ | ✓ | ✓ | ✓ |
| semantic events | ✓ | ✓ | ✓ | ✓ |
| reset versus survive | ✓ | ✓ | ✓ | ✓ |
| history/direct routes | ✓ | supporting | ✓ | ✓ |
| OOB related projections | ✓ | supporting | ✓ | ✓ |
| security and errors | ✓ | ✓ | ✓ | ✓ |
| preservation/morphing exceptional | ✓ | ✓ | ✓ | ✓ |
| testing/operational checks | ✓ | supporting | ✓ | ✓ |

“Supporting” means the topic appears but is not the guide’s main teaching axis.

## Claims intentionally not promoted to universal rules

The package avoids claiming that:

- every feature must use both libraries;
- every modal must use the same implementation;
- all validation failures must use HTTP `200`;
- all applications must be progressively enhanced to the same degree;
- OOB swaps are always preferable to separate requests;
- morphing is inherently bad;
- Alpine stores are forbidden;
- `fetch()` is forbidden;
- rich client islands are forbidden.

Each is a design choice governed by ownership, product requirements, and demonstrated need.

## Final audit outcome

No fundamental contradiction was found among the four source guides. The main work was to:

- consolidate repeated doctrine;
- distinguish official behavior from team convention;
- make version-sensitive behavior explicit;
- replace ambiguous selectors and oversimplified snippets;
- add production failure, focus, CSP, cache, and migration details;
- turn the material into progressive, testable daily exercises.