v0.3.1 with Saxon fully working

README.md

@@ -1,2 +1,104 @@
-# xslt-tools
+# XSLT tools
 
+Browser-only MVP for testing local XML/XSLT transformations. Nothing is uploaded; the app uses browser APIs, LocalStorage, and local file open/save dialogs where available.
+
+## Features in this MVP
+
+- Three-column workbench:
+  - XML input
+  - XSL transformation code
+  - XML output
+- CodeMirror editors with:
+  - line numbers
+  - XML syntax highlighting
+  - editor undo/redo
+  - cut/copy/paste helpers
+  - find support via CodeMirror shortcuts
+- Transformation engines:
+  - SaxonJS 2.7 as the default engine for XSLT 1.0/2.0/3.0-style workflows
+  - Browser-native `XSLTProcessor` as a lightweight XSLT 1.0 fallback
+- XML and XSLT well-formedness checks
+- Basic XSLT root/version checks
+- Snippet toolbox for common XSLT constructs
+- Open/save local files
+  - File System Access API when supported
+  - file input/download fallback otherwise
+- Output → Input action for chained transformations
+- Confirmation dialog before destructive overwrites
+- LocalStorage persistence
+- Approximate “explain transformation” table after a run
+
+## SaxonJS note
+
+SaxonJS is bundled through the `saxon-js` npm package and loaded lazily when the SaxonJS engine runs. The browser build may show Vite warnings about Node modules such as `fs`, `path`, or `stream` being externalized. Those warnings come from the package containing Node.js support as well; the app does not use file-based SaxonJS APIs in the browser.
+
+SaxonJS itself is free to use but not open source. Check `node_modules/saxon-js/LICENSE.txt` after installation before distributing a packaged version.
+
+## Run locally
+
+```bash
+npm install
+npm run dev
+```
+
+Then open the local Vite URL shown in your terminal.
+
+## Build
+
+```bash
+npm run build
+npm run preview
+```
+
+## Suggested next steps
+
+1. Add parameter handling for `xsl:param`.
+2. Add a real diagnostics/lint bridge into CodeMirror gutter markers.
+3. Add transformation test cases with expected output assertions.
+4. Add project import/export as a single `.xslt-tools.json` file.
+5. Improve explain mode through stylesheet instrumentation.
+6. Add optional precompiled SEF import/export support for larger SaxonJS projects.
+
+## Structure
+
+```text
+src/
+├── components/     # Layout, toolbar, editor panels, dialogs
+├── editor/         # CodeMirror integration and XSLT snippets
+├── file/           # Local file open/save helpers
+├── transform/      # Transform engine abstraction, SaxonJS, native engine
+├── validation/     # XML/XSLT validation helpers
+└── workspace/      # LocalStorage-backed workbench state
+```
+
+## Development checks
+
+Use Node.js 22 or newer. The main local quality gate is:
+
+```bash
+npm run check
+```
+
+Useful individual commands:
+
+```bash
+npm run typecheck      # TypeScript only
+npm run lint           # ESLint
+npm run lint:fix       # ESLint autofix where possible
+npm run format:check   # Prettier check
+npm run format         # Prettier write
+npm run test           # Vitest/jsdom test suite
+npm run build          # Production build
+npm run clean          # Remove generated build/cache files
+```
+
+The vendored SaxonJS browser file is intentionally excluded from ESLint and Prettier because it is a third-party distribution artifact.
+
+## Transformation engines
+
+The app currently exposes two engines:
+
+- **SaxonJS 2 dynamic XSLT 3.0**: default engine. It lazy-loads `public/vendor/saxon/SaxonJS2.js`, compiles raw XSLT text to SEF in the browser, then executes the generated SEF locally.
+- **Native browser XSLTProcessor**: XSLT 1.0 fallback using the browser implementation.
+
+The SaxonJS runtime is loaded only when a Saxon transformation is requested, so the initial app shell does not block on the large compiler/runtime file.