naizo.js
Self-persisting HTML for human & AI workflows.
naizo.js is a zero-dependency JavaScript library that turns any single
.html file into a self-saving local-first application – from custom
dashboards, interactive studios, and personal trackers to calculators, notebooks, specs,
and more.
Your data lives in a built-in JSON block (<script id="naizodb">) right
inside the HTML file, so humans in the browser and AI agents on disk can read, build, and
update the exact same file without a backend server.
Why Naizo?
A single .html file is one of the simplest, most versatile formats on a
computer. Whether you write one by hand with a few HTML tags or generate one in seconds
with an AI agent, a single file can be a custom dashboard, an interactive studio, a
personal tracker, a calculator, a notebook, or a living specification – far richer than
plain Markdown, with zero build tools or framework setup.
Yet standard HTML has two everyday limits:
edits in the browser vanish on refresh, and saving to
localStorage traps your changes inside your browser profile where the
.html file on disk – and any CLI or IDE AI agent working alongside you –
cannot see them.
In Japanese, naizō (ないぞう) has two meanings that share the
same pronunciation – and naizo.js brings both to standard HTML with a single
<script> tag:
Everything lives inside one self-contained .html file. Your document
carries its own clean, readable JSON database (#naizodb) right inside
<head> alongside its layout and styles – no backend server to host
and no separate .json sidecar file to manage.
Plain HTML markup is a static skeleton. naizo.js gives it working
internal organs: fields and text blocks that remember what you type, repeating lists
you can add to or reorder on the fly, and two-way sync between your browser and the
.html file on disk.
One HTML File, Shared by Humans & AI Agents
Humans prefer interacting with visual controls in the browser (and writing clean, readable
HTML without boilerplate); AI agents prefer reading and updating structured JSON on disk.
naizo.js connects both inside a single .html file:
-
1. Edit in Your Browser
Type into headings, form inputs, notes, or interactive checklists just like any web app. Every change is saved immediately in the browser so you never lose work when reloading the tab.
-
2. Clean Built-In Data (#naizodb)
Instead of scattering state across noisy HTML attributes, your layout stays clean in
<body>while your data lives in a structured JSON block (#naizodb) in<head>– easy for humans to inspect and effortless for AI agents to read or edit. -
3. Saved Straight to Your File
Click the status pill in the bottom-right corner (or press
⌘S/Ctrl+S) once to link your local.htmlfile. From then on, saving writes your updated data directly back into that file on your computer – no shortcuts to memorize, cleangit diffhistory, and one self-contained file. -
4. Live Co-Editing with AI Agents
While your file is linked, you and your AI agent (Claude Code, Cursor, Antigravity, Codex, or Gemini CLI) can work on it together. When the agent updates the file on disk, your open browser tab picks up the changes automatically within ~2 seconds without interrupting what you are typing.
Human in Browser ──(Edit UI + Status Pill / ⌘S saves to file)──► Single .html file on disk (#naizodb)
◄──(Auto-syncs external disk edits in ~2 s)──── CLI / IDE AI Agent or Editor
Under the Hood Technical architecture & sync guarantees
-
Template vs. Data
<script id="naizodb" type="application/json">holds 2-space-indented JSON ({ _meta, fields, lists, custom }with<escaped as\u003c).<body>acts as the template; form attributes (value,checked,selected) are baked into HTML only when exporting a standalone snapshot (Naizo.exportHTML()/⬇ Save to PC). -
Surgical Disk Writes
In Chromium browsers (Chrome, Edge, Brave, Arc), linking a local file via the File System Access API stores the handle in IndexedDB (
NaizoDB_Handles) and surgically replaces only the<script id="naizodb">block on disk. Runtime DOM mutations from third-party libraries (Tailwind CDN, Lucide, Mermaid) never pollute your source file. -
3-Way Key Merge & Restore
A lightweight ~2 s
file.lastModifiedwatcher (plus tab-focus and pre-write checks) compares per-keyfnv1a:hashes acrossfields,lists, andcustom. Unrelated human and agent edits merge cleanly, focused inputs (document.activeElement) are protected from mid-keystroke overwrites, and same-key collisions are backed up tolocalStoragewith a 1-click↺ Restorebutton in the status pill. -
Pass-Through Data Safety
Unbound fields, unbound lists, and extra list-item properties (such as
id,createdAt, or custom metadata) are preserved in the in-memory store and per-rowWeakMapso agent-authored data is never dropped when a human edits the UI.
Live Playground & #naizodb Inspector
Try a self-persisting HTML app right inside this page. Edit any field,
check off or reorder tasks, or drag the custom slider below, then watch the
#naizodb JSON state update live in the inspector drawer – or click
Save to PC in the bottom-right status pill to download this page as a
local app on your computer.
OAuth2 & Rate-Limiting Spec
naizo-list="tasks")
Hover row for ↑ ↓ ×
contenteditable="true" naizo="notes")
Naizo.get / Naizo.set +
naizo-ignore)
<script id="naizodb" type="application/json"> Live canonical JSON state
Loading #naizodb...
Build a Self-Saving HTML File in 60 Seconds
Easy for humans to write by hand, and effortless for AI agents to generate. No Node.js, bundler, or backend server is required – just standard HTML and a couple of readable attributes:
-
1. Embed #naizodb
Place
<script id="naizodb" type="application/json">and thenaizo.jsscript tag inside<head>. -
2. Bind Your HTML
Add
naizo="key"to fields you want to persist andnaizo-list="name"+naizo-itemto repeating lists in<body>. -
3. Link & Save
Open the
.htmlfile in your browser and click the bottom-right status pill (or press⌘S/Ctrl+S) to link it on disk – or click Save to PC when viewing a hosted page online.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script id="naizodb" type="application/json">
{
"_meta": {},
"fields": { "title": "Launch Plan" },
"lists": { "tasks": [{ "done": false, "task": "Review architecture" }] },
"custom": {}
}
</script>
<script src="https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.js" defer></script>
</head>
<body>
<h1 contenteditable="true" naizo="title">Launch Plan</h1>
<div naizo-list="tasks">
<div naizo-item>
<label><input type="checkbox" naizo="done" /></label>
<label><input type="text" naizo="task" /></label>
</div>
</div>
</body>
</html>
<script src="https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.min.js" defer></script>
<script src="https://unpkg.com/naizojs@latest/dist/naizo.js" defer></script>
# 1. GitHub CLI (installs from the latest published release)
gh skill install nickosh/naizo naizo
# 2. npm Skills CLI
npx skills add nickosh/naizo --skill naizo
# 3. Direct curl (Antigravity, Cursor, Codex, Gemini CLI / Claude Code)
mkdir -p .agents/skills/naizo && curl -fsSL https://naizo.js.org/SKILL.md -o .agents/skills/naizo/SKILL.md
mkdir -p .claude/skills/naizo && curl -fsSL https://naizo.js.org/SKILL.md -o .claude/skills/naizo/SKILL.md
<!-- In-development runtime directly from main (or local ./dist/naizo.js) -->
<script src="https://cdn.jsdelivr.net/gh/nickosh/naizo@main/dist/naizo.js" defer></script>
# In-development AI skill from main
gh skill install nickosh/naizo naizo@main
npx skills add nickosh/naizo@main --skill naizo
mkdir -p .agents/skills/naizo && curl -fsSL https://raw.githubusercontent.com/nickosh/naizo/main/skills/naizo/SKILL.md -o .agents/skills/naizo/SKILL.md
Starter App Blueprints
Ready-to-use single-file HTML applications. Because
<body> is standard HTML, CSS, and JavaScript and
#naizodb stores arbitrary JSON (fields, lists,
custom), you can build everything from simple checklists to multi-pane
studios. Open any blueprint below to try it online, or click
Save to PC in the status pill to use and customize it on your computer.
Minimal spec sheet with an editable heading, owner and status fields, summary textarea, and repeating milestone checklist.
Pre-release sign-off sheet with reviewer metadata, environment dropdown, release readiness toggle, prioritized checks, and blocker notes.
Zero-DOM-wipe multi-note workspace on [naizo-list="notes"] with sidebar
search, category filtering, pinning, live word/task counters, and
Alt+N / Alt+↑/↓ navigation.
Filterable card grid with custom per-card JSON key-value properties (pass-through
keys), <dialog> modals, dynamic location filter options, and live
KPI summaries.
Declarative HTML Attributes & window.Naizo API
Start with simple HTML attributes; reach for JavaScript only when building custom
widgets.
Every attribute supports both concise naizo / naizo-* syntax and
HTML5-compliant data-naizo / data-naizo-* aliases (for example,
naizo="key" or data-naizo="key").
Attribute (or data-*) |
Target Element | Behavior |
|---|---|---|
naizo="key" |
<input>, <textarea>,
<select>, <details>,
[contenteditable], leaf
|
Binds element state to fields["key"] (or item property inside
[naizo-item]).
|
naizo-list="name" |
<div>, <ul>, <tbody>
|
Declares a repeating list bound to lists["name"] and appends
+ Add Item.
|
naizo-item |
Direct child of [naizo-list] |
Marks a repeating row/card with hover ↑ ↓ × controls and
WeakMap pass-through keys.
|
naizo-template |
<template> in list |
Optional explicit blueprint for new items (auto-inferred from first item when omitted). |
naizo-add="name" |
<button> |
Appends a new blank item to [naizo-list="name"]. |
naizo-remove |
<button> in item |
Removes the enclosing [naizo-item] row. |
naizo-move="up|down" |
<button> in item |
Moves the enclosing [naizo-item] row up or down. |
naizo-no-controls |
[naizo-list] |
Disables automatic injection of + Add Item and row toolbars. |
naizo-ignore |
Any element | Excludes element/subtree from state binding while preserving it in exported HTML. |
naizo-strip |
Any element |
Excludes element/subtree from state binding and strips it from auto-templates and
exported/downloaded HTML (⬇ Save to PC).
|
naizo-id="scope" |
<html> or <body> |
Optional document scope identifier to isolate storage keys on
localhost.
|
naizo-mode="online|local|auto" |
<html> or <body> |
Overrides automatic Local Mode vs. Online Mode detection. |
naizo-manual |
<html>, <body>, or
<script>
|
Opts out of automatic boot so you can call Naizo.init() manually.
|
// Programmatic JavaScript API (window.Naizo / window.NaizoDB)
Naizo.get('rateLimitRps'); Naizo.set('rateLimitRps', 250); Naizo.delete('oldKey');
Naizo.getField('owner'); Naizo.setField('owner', 'Kenji'); Naizo.deleteField('flag');
Naizo.getList('tasks'); Naizo.addItem('tasks', { done: false, title: 'Ship', priority: 'High' });
Naizo.updateItem('tasks', 0, { done: true }); Naizo.moveItem('tasks', 1, 0); Naizo.removeItem('tasks', 2);
Naizo.bind(rootEl); await Naizo.save(); Naizo.reset();
await Naizo.unlink(); await Naizo.copyJSON();
const html = Naizo.exportHTML(); const portable = Naizo.downloadHTML('app.html');
// Events: 'naizo:hydrate', 'naizo:change', 'naizo:item'
Browser & Mode Capability Matrix
One HTML file that adapts to where you open it. Whether you open a file
locally from your computer (file:// or localhost) or host it
online (https://), naizo.js adapts automatically and keeps the
bottom-right status pill clear about where your changes are saved.
| Mode & Browsers | Status Pill & Action | Persistence, Sync, & Recovery |
|---|---|---|
|
Local Mode (Live Disk) Chrome, Edge, Brave, Arc on file:// or localhost
|
Browser Cache · Click to Link Disk
↓ after linking Synced to Disk |
⌘S / Ctrl+S links or saves immediately; surgical
<script id="naizodb"> in-place write; immediate disk flush on
tab switch; IndexedDB handle persistence; ~2 s
file.lastModified watch; 3-way shallow key merge with
↺ Restore backup.
|
|
Online Mode (Web Host) All modern browsers on GitHub Pages or https://
|
Saved in Browser
Actions: ⬇ Save to PC · ↺ Reset
|
Instant localStorage persistence + cross-tab
storage merge; ↺ Reset with inline Shadow DOM
confirmation and ↺ Restore undo backup;
⬇ Save to PC (Naizo.downloadHTML()) rewrites relative
naizo.js paths to dist/naizo.min.js on the npm CDN and
strips naizo-mode="online" so downloaded .html files run
in Local Mode on a PC.
|
|
Local Mode (Fallback) Safari & Firefox on file:// or localhost
|
Browser Cache · Click to Save HTML
Action: 📋 Copy
|
Full reactive bindings, [naizo-list] repeater, and
localStorage cache; 1-click
📋 Copy (Naizo.copyJSON()) to copy
#naizodb JSON to clipboard; 1-click clean .html snapshot
download via Naizo.exportHTML().
|