Claro/docs/FUTURE_FEATURES_ROADMAP.md

Claro Future Features Roadmap

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: Grow Claro from a beginner scripting language into a stable accessible platform without breaking the learning-friendly core.

Architecture: Keep the interpreter small and stable. Add major systems behind explicit commands, feature flags, and testable layers. Prefer beginner-readable commands first, then deeper professional tooling around them.

Tech Stack: C99 interpreter, .claro tests/golden outputs, optional helper tools in Python, optional platform libraries such as SDL only after isolated build support exists.

---

Current note: Some tasks in this implementation plan have since been partially completed or moved into dedicated status docs. For the current high-level view, start with ROADMAP.md, CURRENT_STATUS.md, and COMPLETE_PLATFORM_ROADMAP.md.

Priority order

1. Advanced static typing foundation — safest immediate win; improves learner feedback and catches mistakes before running.
2. Professional IDE foundations — language metadata, diagnostics, formatter, LSP/documentation support.
3. Concurrency as real runtime feature — cooperative tasks first; avoid native threads until semantics are clear.
4. Production-grade web programming — HTTP primitives, JSON, routing/server design after safety model.
5. GUI/game engine features — separate stable placeholder graphics from real optional SDL/GUI backends.
6. Online package registry — design package metadata/security before network install.
7. Advanced compiler optimization — only after semantics stabilize; start with bytecode/AST planning, not premature optimization.

---

Track A: Advanced Static Typing

Task A1: Add typed LIST and MAP declarations

Objective: Accept and check beginner-readable container type declarations such as SET names LIST OF TEXT and SET scores MAP OF NUMBER.

Files:

• Modify: src/claro.c
• Test: tests/40_static_container_good.claro
• Test: tests/40_static_container_good.out
• Test: tests/typecheck_container_bad.claro

Steps:

1. Add a failing good test with LIST OF TEXT and MAP OF NUMBER declarations.
2. Add a failing bad typecheck test where a LIST OF NUMBER receives text.
3. Teach claro_is_type_word, claro_type_matches, and the typecheck parser to preserve simple container annotations.
4. Verify claro test and claro typecheck tests/typecheck_container_bad.claro.

Task A2: Add clearer type mismatch messages

Objective: Make type errors explain the variable, expected type, actual value kind, and line number in plain language.

Files:

• Modify: src/claro.c
• Test: tests/typecheck_bad.claro

Steps:

1. Capture current bad output.
2. Improve wording without changing successful behavior.
3. Update tests/docs only after verifying the new wording is clearer.

---

Track B: Professional IDE Foundations

Task B1: Expand claro ide JSON

Objective: Output commands, snippets, type names, and file extension metadata for editor plugins.

Files:

• Modify: src/claro.c
• Test: tests/41_ide_metadata.claro or a CLI validation script.

Steps:

1. Add expected JSON fields: commands, snippets, diagnostics, version.
2. Validate with Python json.loads.
3. Document in docs/IDE.md.

Task B2: Build minimal LSP helper

Objective: Provide a Python helper that reads Claro files and returns diagnostics using claro check/typecheck.

Files:

• Create/modify: support/lsp/claro_lsp_stub.py
• Create: docs/IDE.md

---

Track C: Real Concurrency

Task C1: Define cooperative task semantics

Objective: Document START TASK, YIELD, WAIT TASK, and TASK STATUS without native threads.

Files:

• Create: docs/CONCURRENCY.md
• Test: future tests/42_tasks_cooperative.claro

Rule: Start cooperative scheduling before OS threads. This keeps beginner programs deterministic.

---

Track D: Web Programming

Task D1: Stabilize HTTP client commands

Objective: Keep HTTP CHECK, HTTP GET, and HTTP SAVE predictable and testable with claro:// URLs.

Files:

• Modify: docs/WEB_SERVER_PLAN.md
• Tests: existing networking tests

Task D2: Design local web server syntax

Objective: Propose beginner-friendly server syntax, but do not implement sockets until parser/runtime tests are ready.

Example future shape:

WEB SERVER 8080
WEB GET "/" DO home
TEACH home request
    RETURN "Hello"
END
WEB START

---

Track E: GUI/Game Engine

Task E1: Separate placeholder graphics from real SDL

Objective: Keep stable no-op graphics commands documented separately from optional SDL backends.

Files:

• Modify: docs/SDL12.md
• Create: docs/GRAPHICS.md

Task E2: Optional SDL prototype branch

Objective: Only after build scripts can find SDL 1.2 reliably, add CLARO_WITH_SDL12 support behind a compile flag.

---

Track F: Online Package Registry

Task F1: Define package manifest and lock security

Objective: Design package metadata, versions, hashes, and allowed sources before downloads.

Files:

• Create: docs/PACKAGE_REGISTRY.md

Rule: No online package install until hash verification and safe paths are implemented.

---

Track G: Optimization

Task G1: Add timing benchmark command

Objective: Measure before optimizing.

Files:

• Create: tests/benchmarks/
• Create: docs/PERFORMANCE.md

Rule: No optimizer work without benchmarks.