# 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.