Kata

A local-first structured text parser and visualizer.

Kata is a worker-first, offline-capable PWA for parsing, inspecting, comparing, and exporting structured text directly in the browser. It is designed for mixed audiences: fast enough for performance-sensitive workflows, but approachable enough for developers who need a self-contained tool with no backend dependency after load.

Access

Delivery

Runtime

Performance

Overview

Kata parses, visualizes, diffs, and exports structured text entirely in-browser. The application is built around Web Workers, virtualized rendering, and progressive file handling so that large documents remain responsive without requiring a backend service.

Capabilities

Requirements

Use the project with the runtime and platform expectations below.

Dependencies

Installation

npm install

Quick Start

Start the local development server:

npm run dev

Common follow-up workflows:

npm run build
npm run preview
npm run check
npm run perf:report

Architecture

Kata follows a worker-first architecture with a thin Preact UI layer, virtualized rendering, and base-aware PWA configuration for local and GitHub Pages deployments.

_{Source: docs/diagrams/architecture.mmd}

Design Principles

• Keep main-thread blocking low by pushing heavy parsing and export work into workers.
• Favor local-first workflows with no required backend after the app shell loads.
• Render only what is visible so large documents remain interactive.
• Keep deployment base paths configurable so the same app works locally and on GitHub Pages.

Performance

Kata treats performance as a first-class project concern. The latest generated summary is available in reports/performance/latest.md.

Lighthouse Summary

Detailed artifacts:

• Latest Markdown summary
• Latest JSON summary
• Versioned report bundle

Development

Use the existing npm scripts and GitHub workflows to keep the repo in a releasable state.

npm run dev
npm run check
npm run build
npm run perf:report

Workflow Notes

• npm run check runs the TypeScript build checks.
• npm run build produces the production Vite bundle.
• npm run perf:report builds, previews, audits, and refreshes tracked performance artifacts.
• The CI workflow runs type-checking and build validation on pushes and pull requests.

Deployment

Kata is deployed to GitHub Pages and uses a configurable app base so the same build can run from / locally and from a repository path in hosted environments.

• Environment: GitHub Pages
• Workflow: Deploy Pages workflow
• Live URL: Kata live site
• Performance automation: Performance Report workflow

Troubleshooting

Use these constraints when local behavior does not match the hosted app or when file access features appear limited.

Note: Workspace folder mode depends on browser support for the File System Access API, so Chromium-based browsers provide the most complete experience.

Note: The performance report workflow needs a Chrome executable. In CI this is provided by browser-actions/setup-chrome; locally you may need to set CHROME_PATH.

Links

Contributing

1. Create a branch from main for the change.
2. Run npm run check and npm run build before opening a pull request.
3. Run npm run perf:report when the change affects runtime or bundle behavior.
4. Open a pull request with enough context to review product, architecture, and performance impact.

Copyright © 2026 Corderro Artz / Vaporsoft.