naizo.js · 内蔵 (built-in) & 内臓 (internal organs) · zero dependencies · ~12.4 KB min+gzip · MIT

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.

01 / CONCEPT

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:

内蔵 – Built-In Everything inside the HTML file

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.

内臓 – Internal Organs Working organs for static HTML

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.

02 / ARCHITECTURE

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:

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.lastModified watcher (plus tab-focus and pre-write checks) compares per-key fnv1a: hashes across fields, lists, and custom. Unrelated human and agent edits merge cleanly, focused inputs (document.activeElement) are protected from mid-keystroke overwrites, and same-key collisions are backed up to localStorage with a 1-click ↺ Restore button 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-row WeakMap so agent-authored data is never dropped when a human edits the UI.

03 / LIVE PLAYGROUND

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.

LIVE PLAYGROUND ARTIFACT · BOUND TO #naizodb Click title or fields to edit

OAuth2 & Rate-Limiting Spec

IMPLEMENTATION CHECKLIST (naizo-list="tasks") Hover row for ↑ ↓ ×
ARCHITECTURE NOTES (contenteditable="true" naizo="notes")
CUSTOM WIDGET (Naizo.get / Naizo.set + naizo-ignore)
120 req/sec
<script id="naizodb" type="application/json"> Live canonical JSON state
Loading #naizodb...
04 / QUICK START

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. Minimal self-persisting HTML template
<!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>
2. jsDelivr CDN (readable)
<script src="https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.js" defer></script>
3. jsDelivr CDN (minified ~12.4 KB gzip)
<script src="https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.min.js" defer></script>
4. unpkg CDN
<script src="https://unpkg.com/naizojs@latest/dist/naizo.js" defer></script>
5. Install AI Agent Skill (gh skill, npx skills, or curl — Antigravity, Cursor, Claude Code, Copilot, Codex, Gemini CLI)
# 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
6. Experimental / In-Development (`main` branch runtime + skill – may include unreleased changes)
<!-- 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
05 / TEMPLATES

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.

Project Specification & Milestones

Minimal spec sheet with an editable heading, owner and status fields, summary textarea, and repeating milestone checklist.

examples/starter.html →
Release Verification Checklist

Pre-release sign-off sheet with reviewer metadata, environment dropdown, release readiness toggle, prioritized checks, and blocker notes.

examples/checklist.html →
Master-Detail Engineering Notebook

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.

examples/notes.html →
Asset & Inventory Studio

Filterable card grid with custom per-card JSON key-value properties (pass-through keys), <dialog> modals, dynamic location filter options, and live KPI summaries.

examples/inventory.html →
06 / CONTRACT

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'
07 / ENVIRONMENTS

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().