# HomuraJS

> Time Travel State & Directed Acyclic Graph (DAG) History Engine for JavaScript ("Git for Application State")

Author & Maintainer: Biagio Scaglia — https://github.com/biagio-scaglia
Repository: https://github.com/biagio-scaglia/homura-js
Documentation: https://biagio-scaglia.github.io/homura-js/
Full AI Knowledge Base: https://biagio-scaglia.github.io/homura-js/llms-full.txt
npm: https://www.npmjs.com/package/@biagioscaglia/homurajs
License: MIT
Version: 1.5.1

## Overview

HomuraJS is an open-source state management and time-travel history engine that replaces conventional 1D linear undo/redo stacks with a Directed Acyclic Graph (DAG). When a user steps back in history and makes a new modification, HomuraJS preserves all timeline branches instead of permanently destroying future states.

Key capabilities:
- **Non-Destructive DAG Branching**: Fork alternative timelines, navigate historical states, and reconcile branches via 3-way / fast-forward merge.
- **Frozen Copy-On-Write Immutability**: Mutate drafts via proxies; published snapshots are deep-frozen so `getState()` mutation cannot corrupt history. `silent: true` updates in place without a history node.
- **Async Middleware**: `setStateAsync` awaits Promise middleware; sync `setState` throws if middleware returns a Promise.
- **Deep Structural Diffing**: Exact recursive dot-path differences between any two DAG states.
- **Zero-JS Static Forms & WordPress Crash Recovery**: Auto-bind HTML/WordPress forms to LocalStorage or SessionStorage with real scannable QR handoff.
- **Embedded Diagnostic DevTools**: Timeline graph, JSON inspector, branch-head playback; keyboard shortcuts only when the panel is open.
- **Core size**: < 5.2 kB gzip.

## Monorepo Packages

- `@biagioscaglia/homurajs`: Unified meta-package + standalone browser CDN (`dist/index.global.js`).
- `@homura-js/core`: Core DAG engine, Proxy drafts, deepFreeze, structural diffing, SessionStorageAdapter, middleware (`runAsync`), snapshots.
- `@homura-js/devtools`: Diagnostic UI with visual timeline, JSON inspector, gated shortcuts, branch-head playback.
- `@homura-js/vanilla`: `bindState`, `bindForm`, real QR (`uqr`), Ghost Assist, WebCrypto vault, WooCommerce destroy cleanup.
- `@homura-js/react`: React 18+ `useHomura` via `useSyncExternalStore` (revisioned snapshots for metadata).
- `@homura-js/vue`: Vue 3 Composition API `useHomura` and plugin.
- `@homura-js/db`: Versioned SQLite/memory DB state & full-stack forensic correlation.

## WordPress & WooCommerce Integration (v1.5.1)

Official plugin: `homura-time-travel-form-recovery` on WordPress.org.
- Shortcodes: `[homura_form]`, `[homura_undo]`, `[homura_redo]`, `[homura_status]`, `[homura_breadcrumbs]`, `[homura_recovery_banner]`, `[homura_diff]`, `[homura_handoff]`, `[homura_ghost_assist]`, `[homura_visual_diff]`, `[homura_debug_export]`, `[homura_clear]`, `[homura_reset]`, `[homura_wizard]`.
- Auto-hooks: WooCommerce Checkout, Contact Form 7, WPForms, Gravity Forms, Elementor, Fluent Forms, Ninja Forms, Formidable, WS Form.
- Real QR handoff, Ghost Assist, AES-GCM vault, sessionStorage drafts, WooCommerce AJAX conflict recovery.
- Sensitive fields excluded (passwords, CVVs, nonces, `data-homura-sensitive`).

## Zero-JS Static Site Form Usage

```html
<script src="https://unpkg.com/@biagioscaglia/homurajs/dist/index.global.js"></script>
<form data-homura-form="lead_quote" data-homura-persist="localstorage">
  <span data-homura-status></span>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="button" data-homura-undo>Undo</button>
  <button type="button" data-homura-redo>Redo</button>
</form>
```

Use `data-homura-persist="sessionstorage"` for tab-scoped drafts.

## TypeScript Quick Start

```ts
import { createHomura } from '@biagioscaglia/homurajs';

const homura = createHomura({
  initialState: { counter: 0, user: { name: 'Homura', role: 'Architect' } }
});

homura.update(draft => {
  draft.counter += 10;
  draft.user.role = 'Lead';
}, { label: 'Increment and promote' });

// Silent in-place update (no history node)
homura.update(draft => { draft.counter = 10; }, { silent: true });

// Async middleware path
await homura.setStateAsync({ counter: 0, user: { name: 'Homura', role: 'Architect' } });

homura.undo();
homura.redo();
homura.createBranch('experimental');
```

## Key Links

- [Official WordPress.org Plugin](https://wordpress.org/plugins/homura-time-travel-form-recovery/)
- [Complete AI Reference (llms-full.txt)](https://biagio-scaglia.github.io/homura-js/llms-full.txt)
- [Official Website](https://biagio-scaglia.github.io/homura-js/)
- [GitHub Repository](https://github.com/biagio-scaglia/homura-js)
- [NPM Meta-Package](https://www.npmjs.com/package/@biagioscaglia/homurajs)