Metadata-Version: 2.4
Name: arabic-web-transpiler
Version: 0.2.0
Summary: Arabic-source web markup transpiler for HTML5, CSS, and JavaScript contexts
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: wheel; extra == "dev"

# Arabic Web Transpiler

`arhtml` is a source-to-source compiler for Arabic-authored web markup. It reads
`.arhtml` and emits browser-ready HTML5 with standard HTML, CSS, and JavaScript
syntax. Generated HTML keeps the release contract `<!doctype html>`,
`dir="rtl"`, and `lang="ar"`.

Current status: phased baseline implementation. HTML elements, attributes,
attribute values, ARIA basics, SVG/MathML basics, CSS token rewriting, and
JavaScript token rewriting are supported through `dictionaries/ar-web-v1.json`.

## CLI

```powershell
python -m arweb examples/static.arhtml -o examples/static.html
```

Use an expanded bundled dictionary by name:

```powershell
python -m arweb examples/minor-v1.1.arhtml -o examples/minor-v1.1.html --dictionary ar-web-v1.1
python -m arweb examples/aria-v1.2.arhtml -o examples/aria-v1.2.html --dictionary ar-web-v1.2
python -m arweb examples/svg-v1.2.arhtml -o examples/svg-v1.2.html --dictionary ar-web-v1.2
python -m arweb examples/mathml-v1.2.arhtml -o examples/mathml-v1.2.html --dictionary ar-web-v1.2
python -m arweb examples/css-v1.2.arhtml -o examples/css-v1.2.html --dictionary ar-web-v1.2
python -m arweb examples/css-visual-v1.3.arhtml -o examples/css-visual-v1.3.html --dictionary ar-web-v1.3
python -m arweb examples/js-browser-v1.3.arhtml -o examples/js-browser-v1.3.html --dictionary ar-web-v1.3
python -m arweb examples/js-parser-v1.3.arhtml -o examples/js-parser-v1.3.html --dictionary ar-web-v1.3
python -m arweb examples/html-v1.4.arhtml -o examples/html-v1.4.html --dictionary ar-web-v1.4
python -m arweb examples/css-effects-v1.5.arhtml -o examples/css-effects-v1.5.html --dictionary ar-web-v1.5
python -m arweb examples/svg-v1.6.arhtml -o examples/svg-v1.6.html --dictionary ar-web-v1.6
python -m arweb examples/js-browser-v1.7.arhtml -o examples/js-browser-v1.7.html --dictionary ar-web-v1.7
python -m arweb examples/mathml-v1.8.arhtml -o examples/mathml-v1.8.html --dictionary ar-web-v1.8
python -m arweb examples/css-modern-v1.9.arhtml -o examples/css-modern-v1.9.html --dictionary ar-web-v1.9
python -m arweb examples/js-components-v1.10.arhtml -o examples/js-components-v1.10.html --dictionary ar-web-v1.10
python -m arweb examples/aria-v1.11.arhtml -o examples/aria-v1.11.html --dictionary ar-web-v1.11
python -m arweb examples/svg-v1.12.arhtml -o examples/svg-v1.12.html --dictionary ar-web-v1.12
python -m arweb examples/mathml-v1.13.arhtml -o examples/mathml-v1.13.html --dictionary ar-web-v1.13
python -m arweb examples/html-v1.14.arhtml -o examples/html-v1.14.html --dictionary ar-web-v1.14
python -m arweb examples/css-current-v1.15.arhtml -o examples/css-current-v1.15.html --dictionary ar-web-v1.15
python -m arweb examples/js-current-v1.16.arhtml -o examples/js-current-v1.16.html --dictionary ar-web-v1.16
python -m arweb examples/aria-v1.17.arhtml -o examples/aria-v1.17.html --dictionary ar-web-v1.17
python -m arweb examples/svg-v1.18.arhtml -o examples/svg-v1.18.html --dictionary ar-web-v1.18
python -m arweb examples/mathml-v1.19.arhtml -o examples/mathml-v1.19.html --dictionary ar-web-v1.19
python -m arweb examples/html-v1.20.arhtml -o examples/html-v1.20.html --dictionary ar-web-v1.20
python -m arweb examples/css-current-v1.21.arhtml -o examples/css-current-v1.21.html --dictionary ar-web-v1.21
python -m arweb examples/js-current-v1.22.arhtml -o examples/js-current-v1.22.html --dictionary ar-web-v1.22
python -m arweb examples/aria-v1.23.arhtml -o examples/aria-v1.23.html --dictionary ar-web-v1.23
python -m arweb examples/svg-v1.24.arhtml -o examples/svg-v1.24.html --dictionary ar-web-v1.24
python -m arweb examples/mathml-v1.25.arhtml -o examples/mathml-v1.25.html --dictionary ar-web-v1.25
```

Start here for a complete walkthrough: [docs/TUTORIAL.md](docs/TUTORIAL.md).
Runnable examples catalog: [docs/EXAMPLES.md](docs/EXAMPLES.md).
Full generated CLI reference: [docs/CLI.md](docs/CLI.md).
Standards coverage roadmap: [docs/STANDARDS_COVERAGE_ROADMAP.md](docs/STANDARDS_COVERAGE_ROADMAP.md).
Arabic-first production ecosystem guide: [docs/PRODUCTION_ECOSYSTEM.md](docs/PRODUCTION_ECOSYSTEM.md).
Product-ready app demo: [docs/PRODUCT_DEMO.md](docs/PRODUCT_DEMO.md).
Compatibility guide: [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
Post-v1.3 expansion selection: [docs/POST_V1_3_EXPANSION_SELECTION.md](docs/POST_V1_3_EXPANSION_SELECTION.md).
Post-v1.8 expansion selection: [docs/POST_V1_8_EXPANSION_SELECTION.md](docs/POST_V1_8_EXPANSION_SELECTION.md).
Post-v1.9 expansion selection: [docs/POST_V1_9_EXPANSION_SELECTION.md](docs/POST_V1_9_EXPANSION_SELECTION.md).
Post-v1.10 expansion selection: [docs/POST_V1_10_EXPANSION_SELECTION.md](docs/POST_V1_10_EXPANSION_SELECTION.md).
Post-v1.11 expansion selection: [docs/POST_V1_11_EXPANSION_SELECTION.md](docs/POST_V1_11_EXPANSION_SELECTION.md).
Post-v1.12 expansion selection: [docs/POST_V1_12_EXPANSION_SELECTION.md](docs/POST_V1_12_EXPANSION_SELECTION.md).
Post-v1.13 expansion selection: [docs/POST_V1_13_EXPANSION_SELECTION.md](docs/POST_V1_13_EXPANSION_SELECTION.md).
Post-v1.13 stabilization selection: [docs/POST_V1_13_STABILIZATION_SELECTION.md](docs/POST_V1_13_STABILIZATION_SELECTION.md).
Post-v1.14 expansion selection: [docs/POST_V1_14_EXPANSION_SELECTION.md](docs/POST_V1_14_EXPANSION_SELECTION.md).
Post-v1.15 expansion selection: [docs/POST_V1_15_EXPANSION_SELECTION.md](docs/POST_V1_15_EXPANSION_SELECTION.md).
Post-v1.16 expansion selection: [docs/POST_V1_16_EXPANSION_SELECTION.md](docs/POST_V1_16_EXPANSION_SELECTION.md).
Post-v1.16 stabilization selection: [docs/POST_V1_16_STABILIZATION_SELECTION.md](docs/POST_V1_16_STABILIZATION_SELECTION.md).
Post-v1.17 expansion selection: [docs/POST_V1_17_EXPANSION_SELECTION.md](docs/POST_V1_17_EXPANSION_SELECTION.md).
Post-v1.18 expansion selection: [docs/POST_V1_18_EXPANSION_SELECTION.md](docs/POST_V1_18_EXPANSION_SELECTION.md).
Post-v1.19 expansion selection: [docs/POST_V1_19_EXPANSION_SELECTION.md](docs/POST_V1_19_EXPANSION_SELECTION.md).
Post-v1.19 stabilization selection: [docs/POST_V1_19_STABILIZATION_SELECTION.md](docs/POST_V1_19_STABILIZATION_SELECTION.md).
Post-v1.20 expansion selection: [docs/POST_V1_20_EXPANSION_SELECTION.md](docs/POST_V1_20_EXPANSION_SELECTION.md).
Post-v1.21 expansion selection: [docs/POST_V1_21_EXPANSION_SELECTION.md](docs/POST_V1_21_EXPANSION_SELECTION.md).
Post-v1.22 expansion selection: [docs/POST_V1_22_EXPANSION_SELECTION.md](docs/POST_V1_22_EXPANSION_SELECTION.md).
Post-v1.22 stabilization selection: [docs/POST_V1_22_STABILIZATION_SELECTION.md](docs/POST_V1_22_STABILIZATION_SELECTION.md).
Post-v1.23 expansion selection: [docs/POST_V1_23_EXPANSION_SELECTION.md](docs/POST_V1_23_EXPANSION_SELECTION.md).
Post-v1.24 expansion selection: [docs/POST_V1_24_EXPANSION_SELECTION.md](docs/POST_V1_24_EXPANSION_SELECTION.md).

## Python API

```python
from arweb import transpile

html = transpile("<قسم><فقرة>مرحبا</فقرة></قسم>")
```

The compiler always emits `<!doctype html>` and guarantees the root output tag
has `dir="rtl"` and `lang="ar"`.

## Dictionaries

- `ar-web-v1.json` is frozen by SHA-256 snapshot.
- `ar-web-v1.1.json` extends v1 and adds newer/less-common vocabulary without
  mutating the frozen baseline.
- `ar-web-v1.2.json` extends v1.1 and adds the first standards-roadmap packets:
  author-facing WAI-ARIA 1.2 roles/states/properties and expanded SVG
  structural, paint, mask, clip, marker, and filter vocabulary, plus MathML
  Core token, script, table, operator, and annotation vocabulary, plus CSS
  layout and box-model vocabulary.
- `ar-web-v1.3.json` extends v1.2 and adds CSS color, typography, transform,
  animation, DOM traversal, browser event, storage, fetch, and URL vocabulary.
- JavaScript scanner hardening preserves regex literals and template text while
  translating `${...}` template expressions.
- `ar-web-v1.4.json` extends v1.3 and adds broader author-facing HTML
  attributes and value contexts for forms, media, metadata, embeds, scripts,
  microdata, and global attributes.
- `ar-web-v1.5.json` extends v1.4 and adds CSS effects, filters, clipping,
  scroll snapping, containment, container-query, and media-query vocabulary.
- `ar-web-v1.6.json` extends v1.5 and adds SVG animation, text layout,
  presentation attributes, geometry helpers, foreign objects, and advanced
  filter value contexts.
- `ar-web-v1.7.json` extends v1.6 and adds browser JavaScript vocabulary for
  timers, animation frames, canvas, class lists, observers, structured data,
  clipboard, media queries, and performance helpers.
- `ar-web-v1.8.json` extends v1.7 and adds MathML operator/layout attributes,
  richer math value contexts, annotation encoding aliases, and CSS math layout
  extension terms.
- `ar-web-v1.9.json` extends v1.8 and adds modern CSS selectors, cascade and
  scoped rules, property registration, UI/form styling, and value/function
  vocabulary.
- `ar-web-v1.10.json` extends v1.9 and adds Web Components, Shadow DOM,
  workers, message channels, streams, abort signals, and IndexedDB-oriented
  JavaScript vocabulary.
- `ar-web-v1.11.json` extends v1.10 and adds remaining ARIA text attributes,
  accessible widget relationship fixtures, live-region and drag/drop values,
  and opaque accessibility data preservation.
- `ar-web-v1.12.json` extends v1.11 and adds SVG paint/presentation attributes,
  marker and mask/clip value contexts, symbol/use composition coverage, and a
  runnable accessible graphic fixture.
- `ar-web-v1.13.json` extends v1.12 and adds MathML enclosures, glyphs,
  alignment markers, linebreaking/indent controls, stacked arithmetic,
  long-division vocabulary, and richer MathML value contexts.
- `ar-web-v1.14.json` extends v1.13 and adds HTML Living Standard authoring
  attributes and values for command buttons, dialog close policy, color input
  alpha/colorspace controls, declarative shadow-root templates, metadata,
  links, script types, hidden-until-found, and heading/discoverability controls.
- `ar-web-v1.15.json` extends v1.14 and adds current CSS authoring vocabulary
  for anchor positioning, scroll/view timelines, view-transition
  pseudo-elements, nested selectors, animation ranges, and animation
  composition.
- `ar-web-v1.16.json` extends v1.15 and adds current JavaScript web application
  APIs for Navigation API, URLPattern, Web Crypto, Web Locks, ClipboardItem,
  Cache Storage, and related events.
- `ar-web-v1.17.json` extends v1.16 and adds WAI-ARIA 1.3-oriented role values
  for comments, marks, suggestions, and image role vocabulary.
- `ar-web-v1.18.json` extends v1.17 and adds remaining practical SVG 2
  authoring vocabulary for cursor controls, transform boxes, radial-gradient
  focal controls, filter resolution, text controls, and font presentation.
- `ar-web-v1.19.json` extends v1.18 and adds Content MathML binding,
  operator, set/list, calculus, vector/matrix, constants, and annotation-XML
  vocabulary.
- `ar-web-v1.20.json` extends v1.19 and adds an HTML Living Standard follow-up
  for `selectedcontent`, page lifecycle and context event handler attributes,
  command dialog values, target keywords, compatibility metadata values, shape
  defaults, and opaque source-set data preservation.
- `ar-web-v1.21.json` extends v1.20 and adds CSS Snapshot 2024/current CSSWG
  follow-up vocabulary for text wrapping, white-space longhands, CSS Values 5
  functions, CSS Color 5 device CMYK, custom functions, mixins, and opaque CSS
  data preservation.
- `ar-web-v1.22.json` extends v1.21 and adds ECMAScript 2025 and current browser
  JavaScript API follow-up vocabulary for iterators, Set operations,
  RegExp.escape, Float16Array, task scheduling, AbortSignal aliases, Service
  Worker workflows, and opaque JavaScript data preservation.
- `ar-web-v1.23.json` extends v1.22 and adds WAI-ARIA 1.3 follow-up vocabulary
  for IDREF relationship aliases, ARIA current/relevant values, ARIA Notify,
  ARIA IDL member terms, and opaque accessibility data preservation.
- `ar-web-v1.24.json` extends v1.23 and adds SVG 2 follow-up vocabulary for
  external-resource and zoom/pan attributes, glyph orientation,
  enable-background values, SVG DOM reflection terms, and opaque SVG data
  preservation.
- `ar-web-v1.25.json` extends v1.24 and adds MathML 4 follow-up vocabulary for
  fallback image attributes, content dictionary groups, maximum width, the
  `MathMLElement` DOM interface, and opaque formula/annotation data preservation.
- Generated dictionary references are in `docs/dictionaries/`.

Refresh generated dictionary docs:

```powershell
python scripts/generate_dictionary_docs.py
```

Check for drift:

```powershell
python scripts/generate_dictionary_docs.py --check
```

Refresh CLI docs:

```powershell
python scripts/generate_cli_docs.py
```

Refresh examples index:

```powershell
python scripts/generate_examples_index.py
```

Check CLI docs:

```powershell
python scripts/generate_cli_docs.py --check
```

Check examples index:

```powershell
python scripts/generate_examples_index.py --check
```

Check v1.3 release review:

```powershell
python scripts/generate_v1_3_release_review.py --check
```

Check v1.8 release review:

```powershell
python scripts/generate_v1_8_release_review.py --check
```

Check v1.13 release review:

```powershell
python scripts/generate_v1_13_release_review.py --check
```

Check v1.16 release review:

```powershell
python scripts/generate_v1_16_release_review.py --check
```

Check v1.19 release review:

```powershell
python scripts/generate_v1_19_release_review.py --check
```

Check v1.22 release review:

```powershell
python scripts/generate_v1_22_release_review.py --check
```

## Packaging Check

The test suite installs the project into a temporary target directory and checks
that bundled dictionaries still work outside the repository layout.

## Project Health

Run the standard verification set:

```powershell
python scripts/project_health.py
```

List the commands without running them:

```powershell
python scripts/project_health.py --list
```

Validate the progress ledger directly:

```powershell
python scripts/check_project_status.py
```

Validate release readiness:

```powershell
python scripts/check_release.py
```

CI runs the same health command on Python 3.11, 3.12, and 3.13.

## Contributing

- Contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Dictionary expansion checklist: [docs/DICTIONARY_EXPANSION_CHECKLIST.md](docs/DICTIONARY_EXPANSION_CHECKLIST.md)
- Release review checklist: [docs/RELEASE_REVIEW_CHECKLIST.md](docs/RELEASE_REVIEW_CHECKLIST.md)
