From bc50d41f9a506b7728235baf899b1a878fa8b371 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 26 Dec 2025 14:14:55 +0000 Subject: [PATCH] Add comprehensive README and development roadmap - Expand README.adoc with full project vision, core concepts, and technology stack documentation - Add ROADMAP.adoc with phased development plan (Foundation through Mobile & Distribution) - Document Ephapax WebFrame and Linear Loader concepts - Include BSL/GSL sign language accessibility vision - Mark current status as specification stage with infrastructure complete --- README.adoc | 237 +++++++++++++++++++++++++++++++++++++++-- ROADMAP.adoc | 294 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 525 insertions(+), 6 deletions(-) create mode 100644 ROADMAP.adoc diff --git a/README.adoc b/README.adoc index 4efb9cc..c7b6c00 100644 --- a/README.adoc +++ b/README.adoc @@ -1,10 +1,235 @@ -= Bridge: Web-Rescript +// SPDX-License-Identifier: MIT OR AGPL-3.0-or-later +// SPDX-FileCopyrightText: 2024-2025 hyperpolymath + += Bridge: Web-ReScript +:toc: macro +:toc-title: Contents +:toclevels: 3 +:icons: font :std: ReScript > WASM :a11y: WCAG 2.3 AAA / BSL Support -== The PWA Standard -A TypeScript-free environment. All frontend logic is written in **ReScript** and compiled to **WASM** matter. +A TypeScript-free Progressive Web Application framework. All frontend logic is written in **ReScript** and compiled to **WebAssembly**. + +[cols="1,1,1,1"] +|=== +|Status |License |Accessibility |Runtime + +|*Specification* +|MIT OR AGPL-3.0+ +|WCAG 2.3 AAA +|Deno + WASM +|=== + +toc::[] + +== Project Status + +[IMPORTANT] +==== +**This repository is currently at the specification stage.** + +The project infrastructure, governance, and vision are in place. Implementation will follow the phases outlined in link:ROADMAP.adoc[ROADMAP.adoc]. +==== + +== Vision + +Bridge is a next-generation PWA framework built on three core principles: + +=== 1. TypeScript-Free Architecture + +All application code is written in **ReScript**, providing: + +* Sound type system with complete inference +* Zero-cost JavaScript interop where needed +* Compilation to optimized WebAssembly + +=== 2. Accessibility as a First-Class Concern + +* **WCAG 2.3 AAA compliance** as the baseline, not an afterthought +* **Sign Language support** (BSL/GSL) built into the resource system +* Semantic structure enforced at the type level + +=== 3. Verified Asset Loading + +* **Ephapax WebFrame**: Assets are cryptographically verified before rendering +* **Linear Loader**: Deterministic, auditable asset loading sequence +* No runtime surprises from tampered resources + +== Core Concepts + +=== The Ephapax WebFrame + +A security boundary that validates all resources before they enter the application context. Resources are integrity-checked against known hashes, ensuring what you ship is what runs. + +=== Linear Loader + +Assets load in a defined, predictable order: + +1. Critical path resources (verified) +2. Progressive enhancement layers +3. Deferred non-essential resources + +This enables: + +* Predictable performance characteristics +* Debuggable load sequences +* Guaranteed resource availability at each stage + +=== Sign Language Resources + +BSL (British Sign Language) and GSL (Generic Sign Language) are treated as first-class content types: + +* Native resource type in the asset system +* Synchronization primitives for video/text pairing +* Fallback chains respecting user preferences + +== Technology Stack + +[cols="2,3,2"] +|=== +|Layer |Technology |Purpose + +|**Frontend** +|ReScript +|Type-safe application logic + +|**Compilation Target** +|WebAssembly +|Performance, sandboxing + +|**Runtime** +|Deno +|Package management, tooling + +|**Build** +|Rust toolchain +|WASM compilation, CLI tools + +|**Mobile** +|Tauri 2.0+ / Dioxus +|Native mobile deployment + +|**Backend** (optional) +|Gleam +|BEAM or JS compilation target + +|**Configuration** +|Nickel +|Type-safe configuration +|=== + +See link:.claude/CLAUDE.md[CLAUDE.md] for the complete Hyperpolymath language policy. + +== Repository Structure + +[source] +---- +bridge-web-rescript/ +├── .claude/ # AI assistant configuration +│ └── CLAUDE.md # Hyperpolymath language policy +├── .github/ +│ ├── ISSUE_TEMPLATE/ # Bug, feature, docs, question templates +│ ├── workflows/ # CI/CD (CodeQL, security, sync) +│ ├── CODEOWNERS # Review requirements +│ ├── FUNDING.yml # Sponsorship configuration +│ └── dependabot.yml # Dependency updates +├── CODE_OF_CONDUCT.md # Community standards +├── CONTRIBUTING.md # Contribution guidelines +├── LICENSE.txt # MIT OR AGPL-3.0+ (dual license) +├── README.adoc # This file +├── ROADMAP.adoc # Development phases +└── SECURITY.md # Security policy +---- + +=== Planned Structure (Post-Implementation) + +[source] +---- +bridge-web-rescript/ +├── src/ # ReScript source +│ ├── core/ # Framework core +│ ├── loader/ # Linear Loader implementation +│ ├── webframe/ # Ephapax WebFrame +│ └── a11y/ # Accessibility primitives +├── lib/ # Shared libraries +├── wasm/ # Rust/WASM components +├── examples/ # Example applications +├── tests/ # Test suite +├── docs/ # Documentation +│ └── architecture/ # ADRs +├── deno.json # Deno configuration +├── flake.nix # Nix flake +└── guix.scm # Guix package definition +---- + +== Getting Started + +[NOTE] +==== +Implementation has not yet begun. This section will be updated when the first development milestone is reached. +==== + +=== Prerequisites (Planned) + +* Deno 2.0+ +* Rust toolchain (for WASM compilation) +* Nix or Guix (for reproducible builds) + +=== Installation (Future) + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/bridge-web-rescript.git +cd bridge-web-rescript + +# Enter development environment +nix develop # or: guix shell + +# Verify setup +deno task check +deno task test +---- + +== Contributing + +Contributions are welcome once implementation begins. See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines. + +The project uses a **perimeter-based contribution model**: + +* **Perimeter 1**: Security-critical (maintainer only) +* **Perimeter 2**: Core features (reviewed contributions) +* **Perimeter 3**: Community sandbox (open contributions) + +== Security + +See link:SECURITY.md[SECURITY.md] for: + +* Vulnerability reporting process +* Supported versions +* Security update policy + +== License + +Dual-licensed under your choice of: + +* **MIT License** - Maximum flexibility +* **AGPL-3.0-or-later** - Copyleft for network services + +See link:LICENSE.txt[LICENSE.txt] for full terms. + +=== Palimpsest Philosophical Overlay + +This project encourages (non-binding) adherence to the https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] principles for consent-based digital interaction. + +== Links + +* link:ROADMAP.adoc[Development Roadmap] +* link:CONTRIBUTING.md[Contributing Guidelines] +* link:SECURITY.md[Security Policy] +* link:.claude/CLAUDE.md[Hyperpolymath Language Policy] + +--- -== Features -* **BSL/GSL Support:** Sign Language as a first-class resource. -* **Linear Loader:** Assets are verified by the Ephapax WebFrame before rendering. +_Part of the Hyperpolymath ecosystem._ diff --git a/ROADMAP.adoc b/ROADMAP.adoc new file mode 100644 index 0000000..724c9d5 --- /dev/null +++ b/ROADMAP.adoc @@ -0,0 +1,294 @@ +// SPDX-License-Identifier: MIT OR AGPL-3.0-or-later +// SPDX-FileCopyrightText: 2024-2025 hyperpolymath + += Bridge: Web-ReScript - Development Roadmap +:toc: macro +:toc-title: Contents +:toclevels: 2 +:icons: font + +This document outlines the development phases for Bridge: Web-ReScript, a TypeScript-free PWA framework with ReScript and WebAssembly. + +toc::[] + +== Current Status + +[cols="1,3"] +|=== +|Phase |Status + +|**Phase 0: Foundation** +|*IN PROGRESS* - Repository infrastructure complete + +|Phase 1: Core Framework +|Not started + +|Phase 2: WebFrame & Loader +|Not started + +|Phase 3: Accessibility Layer +|Not started + +|Phase 4: Mobile & Distribution +|Not started +|=== + +--- + +== Phase 0: Foundation [CURRENT] + +=== Completed + +* [x] Repository structure and governance +* [x] License selection (MIT OR AGPL-3.0+) +* [x] Security policy (SECURITY.md) +* [x] Contribution guidelines (CONTRIBUTING.md) +* [x] Code of conduct +* [x] GitHub infrastructure +** [x] Issue templates (bug, feature, docs, question) +** [x] CODEOWNERS with perimeter-based review +** [x] Dependabot configuration +** [x] CodeQL security scanning +** [x] Instant-sync for multi-forge propagation +* [x] Hyperpolymath language policy (CLAUDE.md) + +=== Remaining + +* [ ] Nix flake (`flake.nix`) for reproducible development environment +* [ ] Guix package definition (`guix.scm`) +* [ ] Deno configuration (`deno.json`) +* [ ] Justfile for task running +* [ ] Initial ADR (Architecture Decision Record) for framework design + +--- + +== Phase 1: Core Framework + +Establish the foundational ReScript infrastructure. + +=== Milestones + +==== 1.1 Development Environment + +* [ ] Complete Nix flake with all dependencies +* [ ] ReScript compiler configuration +* [ ] Deno integration for tooling +* [ ] Development server setup + +==== 1.2 ReScript Core Module + +* [ ] Project structure (`src/core/`) +* [ ] Type definitions for framework primitives +* [ ] Module system design +* [ ] JavaScript/Deno interop layer + +==== 1.3 WASM Compilation Pipeline + +* [ ] Rust toolchain integration +* [ ] ReScript → WASM compilation path +* [ ] Build optimization pipeline +* [ ] Source maps for debugging + +==== 1.4 Testing Infrastructure + +* [ ] Unit test framework selection +* [ ] Integration test harness +* [ ] CI pipeline for automated testing +* [ ] Coverage reporting + +=== Deliverables + +* Working ReScript → WASM build pipeline +* "Hello World" application compiling to WASM +* Development environment documentation +* ADRs for major decisions + +--- + +== Phase 2: WebFrame & Loader + +Implement the security and asset loading systems. + +=== Milestones + +==== 2.1 Ephapax WebFrame + +* [ ] Resource integrity verification system +* [ ] Hash-based asset validation +* [ ] Security boundary implementation +* [ ] Violation handling and reporting + +==== 2.2 Linear Loader + +* [ ] Resource loading sequence definition +* [ ] Critical path identification +* [ ] Progressive enhancement layers +* [ ] Deferred loading system + +==== 2.3 Asset Pipeline + +* [ ] Asset manifest generation +* [ ] Build-time integrity hash computation +* [ ] Cache-busting strategy +* [ ] Service worker integration + +==== 2.4 Developer Experience + +* [ ] Hot module replacement (HMR) +* [ ] Development mode bypass (with warnings) +* [ ] Asset debugging tools +* [ ] Load sequence visualization + +=== Deliverables + +* Secure asset loading system +* Deterministic load ordering +* Developer tooling for asset management +* Security documentation + +--- + +== Phase 3: Accessibility Layer + +Implement first-class accessibility support. + +=== Milestones + +==== 3.1 WCAG 2.3 AAA Compliance + +* [ ] Semantic HTML generation +* [ ] ARIA attribute system +* [ ] Focus management +* [ ] Keyboard navigation + +==== 3.2 Sign Language Support + +* [ ] BSL/GSL resource type definition +* [ ] Video/text synchronization primitives +* [ ] Preference detection and storage +* [ ] Fallback chain system + +==== 3.3 Type-Level Accessibility + +* [ ] ReScript types enforcing a11y requirements +* [ ] Compile-time accessibility validation +* [ ] Accessible component library +* [ ] Pattern documentation + +==== 3.4 Testing & Validation + +* [ ] Automated a11y testing integration +* [ ] Screen reader testing protocol +* [ ] User testing framework +* [ ] Compliance reporting + +=== Deliverables + +* WCAG 2.3 AAA compliant component library +* Sign language resource system +* Accessibility testing suite +* User documentation for a11y features + +--- + +== Phase 4: Mobile & Distribution + +Extend to mobile platforms and production distribution. + +=== Milestones + +==== 4.1 Tauri 2.0 Integration + +* [ ] Tauri project structure +* [ ] ReScript ↔ Rust bridge +* [ ] iOS build configuration +* [ ] Android build configuration + +==== 4.2 PWA Features + +* [ ] Service worker generation +* [ ] Offline-first architecture +* [ ] Push notification support +* [ ] Install prompts + +==== 4.3 Distribution + +* [ ] App store build pipelines +* [ ] Web deployment automation +* [ ] CDN configuration +* [ ] Analytics integration (privacy-respecting) + +==== 4.4 Documentation & Examples + +* [ ] Getting started guide +* [ ] API documentation +* [ ] Example applications +* [ ] Migration guides (from other frameworks) + +=== Deliverables + +* Production-ready mobile deployment +* PWA with full offline support +* Distribution automation +* Comprehensive documentation + +--- + +== Future Considerations + +Items not currently scheduled but under consideration: + +=== Gleam Backend Integration + +* Server-side rendering with Gleam +* API generation from ReScript types +* BEAM deployment option + +=== Dioxus Alternative + +* Pure Rust UI option +* Native performance path +* Shared Rust/WASM components + +=== Ecosystem + +* Plugin system +* Theme/styling framework +* Form handling library +* State management patterns + +=== Community + +* Contributor onboarding program +* Example application showcase +* Integration guides for common services + +--- + +== Contributing to the Roadmap + +This roadmap is a living document. To propose changes: + +1. Open an issue with the `roadmap` label +2. Describe the proposed addition or modification +3. Explain the rationale and any dependencies +4. Discuss with maintainers + +See link:CONTRIBUTING.md[CONTRIBUTING.md] for general contribution guidelines. + +--- + +== Changelog + +[cols="1,1,3"] +|=== +|Date |Version |Changes + +|2025-01 +|0.1.0 +|Initial roadmap creation +|=== + +--- + +_Last updated: 2025-01_