The Directed Acyclic Graph State Engine for JavaScript.

export interface HistoryEntry<T> {
  id: string;              // UUIDv4 node identifier
  parentId: string | null; // Direct ancestor pointer
  childrenIds: string[];   // Successor branches (forks)
  branchId: string;        // Active timeline branch
  timestamp: number;       // Unix epoch ms
  label: string;           // Semantic operation descriptor
  state: T;                // Frozen immutable snapshot
  metadata?: Record<string, unknown>;
}

npm install @biagioscaglia/homurajs

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

interface AppState {
  counter: number;
  user: { name: string; role: string };
}

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

// Mutate via Copy-On-Write Proxy Draft
homura.update(draft => {
  draft.counter += 10;
  draft.user.role = 'Lead';
}, { label: 'Promote user and increment' });

// Non-destructive Time Travel
homura.undo(); // State reverts to counter: 0
homura.redo(); // State returns to counter: 10

// Branching
homura.createBranch('experimental');
homura.update(draft => { draft.counter = 999; });

// Atomic Transactions: Multiple operations collapsed into a single DAG node
homura.transaction(draft => {
  draft.counter += 50;
  draft.user.name = 'Madoka';
  draft.user.role = 'Guardian';
}, { label: 'Atomic Profile Update' });

const diffs = homura.diff('entry-node-a', 'entry-node-b');
// Returns:
// [
//   { type: 'modified', path: 'user.role', oldValue: 'Architect', newValue: 'Lead' },
//   { type: 'added', path: 'flags.experimental', newValue: true }
// ]

<!-- CDN Standalone Script -->
<script src="https://unpkg.com/@biagioscaglia/homurajs/dist/index.global.js"></script>

<!-- Declarative Auto-Bound Form -->
<form data-homura-form="lead_capture" data-homura-persist="localstorage">
  <span data-homura-status></span>
  <div data-homura-breadcrumbs></div>

  <input type="text" name="name" placeholder="Full Name" />
  <input type="email" name="email" placeholder="Email Address" />
  <textarea name="specifications"></textarea>

  <button type="button" data-homura-undo>Undo</button>
  <button type="button" data-homura-redo>Redo</button>
  <button type="submit">Submit Form</button>
</form>

<form data-homura-wizard="quote_wizard" data-homura-persist="localstorage">
  <div data-homura-step="1">
    <label>Step 1: Budget</label>
    <input type="number" name="budget" />
    <button type="button" data-homura-next>Next Step</button>
  </div>
  <div data-homura-step="2">
    <label>Step 2: Contact</label>
    <input type="email" name="email" />
    <button type="button" data-homura-prev>Back</button>
    <button type="submit" data-homura-next data-submit-label="Finish">Submit</button>
  </div>
</form>

[homura_form id="lead_quote" persist="localstorage" crypto="aes-gcm"]
  [homura_status form="lead_quote"]
  [homura_breadcrumbs form="lead_quote"]
  [homura_ghost_assist form="lead_quote"]

  <input type="text" name="company" placeholder="Company Name" />
  <textarea name="project_scope" placeholder="Describe scope..."></textarea>

  [homura_undo form="lead_quote" label="Undo"]
  [homura_redo form="lead_quote" label="Redo"]
  [homura_handoff form="lead_quote" label="📱 Continue on Mobile"]
  [homura_visual_diff form="lead_quote" field="project_scope" label="📝 Visual Diff"]
  [homura_clear form="lead_quote" label="Clear Draft"]
[/homura_form]

import React from 'react';
import { useHomura } from '@homura-js/react';
import { homura } from './store';

export function UserDashboard() {
  const { state: user, update, undo, redo, canUndo, canRedo } = useHomura(
    homura,
    s => s.user
  );

  return (
    <div>
      <h3>User: {user.name}</h3>
      <button onClick={() => update(d => { d.user.name = 'New Name'; })}>Update</button>
      <button disabled={!canUndo} onClick={() => undo()}>Undo</button>
      <button disabled={!canRedo} onClick={() => redo()}>Redo</button>
    </div>
  );
}

<template>
  <div>
    <h3>Counter: {{ state.counter }}</h3>
    <button @click="increment">+1</button>
    <button :disabled="!canUndo" @click="undo">Undo</button>
    <button :disabled="!canRedo" @click="redo">Redo</button>
  </div>
</template>

<script setup lang="ts">
import { useHomura } from '@homura-js/vue';
import { homura } from './store';

const { state, update, undo, redo, canUndo, canRedo } = useHomura(homura);

function increment() {
  update(d => { d.counter++; }, { label: 'Increment' });
}
</script>

import { mountDevTools } from '@homura-js/devtools';

// Mount interactive Visual Time Machine
mountDevTools(homura, {
  position: 'floating', // 'floating' | 'embedded'
  theme: 'dark',
  defaultOpen: true
});

// Keyboard Navigation Active:
// [← / Undo]  [→ / Redo]  [Space / Play-Pause]  [Home / Rewind]  [End / Latest]

import { diffStatesAsync, createAsyncDiffer } from '@biagioscaglia/homurajs';

// Offload heavy structural diffing to background Web Worker thread
const changes = await diffStatesAsync(largeDataSetA, largeDataSetB, {
  timeoutMs: 3000
});

console.log('Detected diffs off-thread:', changes);

// 1. Client / User encounters an unexpected bug in production
window.addEventListener('error', () => {
  // Capture 100% of the DAG state evolution up to the moment of failure
  const sessionData = homura.export();
  sendErrorReport('crash-session.homura', sessionData);
});

// 2. Developer imports the session in DevTools or local environment
homura.import(crashSessionData);

// 3. Replay the exact sequence of user actions that corrupted the state
await homura.replay({
  speed: 2,
  onStep: (entry, step, total) => {
    console.log(`[Step ${step}/${total}] Transition: ${entry.label}`, entry.state);
  }
});
// 4. Jump directly to the failing node and compute the recursive structural diff
  homura.jumpTo('corrupted-node-id');
  const diffs = homura.diff('previous-valid-node', 'corrupted-node-id');

import { createHomuraDB, createForensicRecorder } from '@homura-js/db';

// 1. Initialize Versioned Database Engine (Embedded SQLite / Memory)
const db = createHomuraDB({ name: 'production_store' });
db.createTable('orders');
db.createTable('inventory');

// 2. Attach Full-Stack Forensic Recorder
const recorder = createForensicRecorder({
  clientHomura, // Frontend UI Homura State (#184)
  db            // Backend Database HomuraDB State (#52)
});

// 3. Correlate HTTP Network Requests with Database Mutations
recorder.recordNetworkTrace({
  url: '/api/checkout',
  method: 'POST',
  statusCode: 200,
  requestBody: { cart: ['cyber_shield_01'] }
});

db.transaction(tx => {
  tx.insert('orders', { id: 'ord_99', total: 250, status: 'confirmed' });
  tx.update('inventory', 'SHIELD-01', { stock: 48 });
}, {
  label: 'Atomic Checkout Transaction',
  clientStateId: clientHomura.getCurrentEntry().id
});

// 4. Export Unified Forensic Session (.homura)
const sessionJSON = recorder.exportJSON();
// sessionJSON contains: Client UI DAG + Network Trace Timeline + Database Mutation DAG

git clone https://github.com/biagio-scaglia/homura-js.git
cd homura-js && pnpm install
pnpm run bench