tjs-lang 0.7.7 → 0.8.0

package/CLAUDE.md

@@ -54,13 +54,7 @@ bun run docs                # Generate documentation
 # Build standalone CLI binaries
 bun run build:cli           # Compiles tjs + tjsx to dist/
 
-# Compatibility testing (transpile popular TS libraries with fromTS)
-bun scripts/compat-zod.ts          # Zod validation library
-bun scripts/compat-effect.ts       # Effect (HKTs, intersections)
-bun scripts/compat-radash.ts       # Radash utilities
-bun scripts/compat-superstruct.ts  # Superstruct validation
-bun scripts/compat-ts-pattern.ts   # ts-pattern matching
-bun scripts/compat-kysely.ts       # Kysely SQL builder
+# Compatibility testing — see scripts/compat-*.ts (zod, effect, radash, superstruct, ts-pattern, kysely)
 
 # Deployment (Firebase)
 bun run deploy              # Build demo + deploy functions + hosting
@@ -99,7 +93,7 @@ bun run functions:serve     # Local functions emulator
 - `src/batteries/` - LM Studio integration (lazy init, model audit, vector search)
 - `src/store/` - Store implementations for persistence
 - `src/rbac/` - Role-based access control
-- `src/use-cases/` - Integration tests and real-world examples (28 test files)
+- `src/use-cases/` - Integration tests and real-world examples (30 test files)
 - `src/cli/tjs.ts` - CLI tool for check/run/types/emit/convert/test commands
 - `src/cli/tjsx.ts` - JSX/component runner
 - `src/cli/playground.ts` - Local playground server
@@ -140,6 +134,10 @@ import { Agent, AgentVM, ajs, tjs } from 'tjs-lang' // Main entry
 import { Eval, SafeFunction } from 'tjs-lang/eval' // Safe eval utilities
 import { tjs, transpile } from 'tjs-lang/lang' // Language tools only
 import { fromTS } from 'tjs-lang/lang/from-ts' // TypeScript transpilation
+import { AgentVM } from 'tjs-lang/vm' // VM only (smaller bundle)
+import { batteryAtoms } from 'tjs-lang/batteries' // LM Studio batteries
+import { dot, norm_sq } from 'tjs-lang/linalg' // SIMD linear-algebra kernels
+// Editor integrations: 'tjs-lang/editors/monaco', '/codemirror', '/ace'
 ```
 
 ### Transpiler Chain (TS → TJS → JS)
@@ -248,7 +246,7 @@ AJS expressions behave differently from JavaScript in several important ways:
 - Unit tests alongside source files (`*.test.ts`)
 - Integration tests in `src/use-cases/` (RAG, orchestration, malicious actors)
 - Security tests in `src/use-cases/malicious-actor.test.ts`
-- Language tests split across 14 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
+- Language tests split across 17 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
 
 Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ overall.
 
@@ -401,6 +399,72 @@ The playground is hosted on Firebase (`tjs-platform.web.app`). Demo build output
 
 The `docs/` directory contains real documentation (markdown), not build artifacts. See `docs/README.md` for the documentation index.
 
+### Playground Examples
+
+The playground (https://tjs-platform.web.app) shows interactive TJS and AJS examples in a navigable sidebar. Examples live as markdown files with embedded code blocks, NOT as raw `.tjs` files.
+
+**Where they live:**
+
+- TJS playground examples: `guides/examples/tjs/<slug>.md`
+- AJS playground examples: `guides/examples/ajs/<slug>.md` (assumed parallel structure)
+
+**File format:**
+
+<!-- prettier-ignore -->
+```markdown
+<!--{"section":"tjs","type":"example","group":"basics","order":16}-->
+
+# Example Title
+
+Short intro paragraph (plain markdown).
+
+​```tjs
+/*#
+## Optional H2 — markdown rendered above the code in the playground
+Explain the concept here. Use markdown freely.
+*/
+
+// Then the actual TJS code
+function demo() { ... }
+
+/**
+ * JSDoc-style /** ... *​/ blocks are also extracted as docs.
+ * Leading ` * ` is stripped from each line; the rest renders as markdown.
+ * Use this when porting TS source where JSDoc is already idiomatic.
+ */
+
+test 'a description' {
+  expect(...).toBe(...)
+}
+​```
+```
+
+Frontmatter fields: `section` (`tjs`/`ajs`), `type: "example"`, `group` (`basics`/`advanced`/etc.), `order` (numeric, controls sidebar position). The H1 becomes the example title in the nav.
+
+**Registration:**
+
+Examples are auto-discovered by `bin/docs.js` (run via `bun run docs`), which walks the markdown tree, parses frontmatter, extracts the `tjs`/`ajs` code block, and writes the result to `demo/docs.json`. The demo loads `docs.json` at runtime — no other registration step.
+
+**After adding/editing an example:** run `bun run docs` and commit the regenerated `demo/docs.json` alongside the `.md` file. (The docs builder also runs as part of `bun run build:demo` and `bun run deploy`.)
+
+**Testing playground examples:**
+
+The CLI (`bun src/cli/tjs.ts run`) does NOT inject the test-block `expect` harness — that's a playground-only thing. So running an extracted code block via the CLI prints "expect is not defined" for any `test { expect(...) }` blocks even though they pass in the playground. To verify an example:
+
+1. **Console-log behavior** (works via CLI): extract the `tjs` code block and run it.
+
+   ````bash
+   awk '/^```tjs$/{flag=1; next} /^```$/{flag=0} flag' \
+     guides/examples/tjs/<slug>.md > /tmp/example.tjs
+   bun src/cli/tjs.ts run /tmp/example.tjs
+   ````
+
+   Verify the printed output matches the expected behavior shown in the example's comments.
+
+2. **Test blocks**: spin up the dev server (`bun run start`) and load the example in the playground UI to confirm tests pass under the real `expect` harness.
+
+3. **Frontmatter / registration**: after `bun run docs`, grep `demo/docs.json` for the slug to confirm it was picked up with the right `section`/`group`/`order`.
+
 ### Additional Directories
 
 - `tjs-src/` — TJS runtime written in TJS itself (self-hosting)
@@ -410,6 +474,10 @@ The `docs/` directory contains real documentation (markdown), not build artifact
 
 ### Additional Documentation
 
+- `llms.txt` — agent-facing navigation index (ships in npm bundle); points to docs and source entry points
+- `guides/footguns.md` — JS footguns TJS fixes (boxed-primitive truthiness, `==` coercion, `typeof null`, uninitialized `let`, etc.). Demo: `examples/js-footguns-fixed.tjs`.
+- `guides/playground-imports.md` — how the playground/dev-server resolves bare imports: TFS service worker, default JSDelivr `/+esm` routing, esm.sh allowlist for peer-dep packages (React), CDN hints (`jsdelivr/`, `esmsh/`, `unpkg/`, `github/`), and full-URL passthrough.
+- `README.md` — Project intro, install, quick start
 - `DOCS-TJS.md` — TJS language guide
 - `DOCS-AJS.md` — AJS runtime guide
 - `TJS-FOR-JS.md` — TJS guide for JavaScript developers (syntax differences, gotchas)
@@ -418,39 +486,37 @@ The `docs/` directory contains real documentation (markdown), not build artifact
 - `AGENTS.md` — Agent workflow instructions (session-completion checklist, push-before-done rule)
 - `TODO.md` — Open work, organized by area; move items to the **Completed** section when done
 - `PLAN.md` — Roadmap
+- `DOCS-WASM.md` — Canonical WASM reference: inline blocks, `wasm function` declarations, memory model, cross-file composition, `tjs-lang/linalg`, current limitations
+- `wasm-library-plan.md` — Cross-file WASM library design (composable `wasm function` declarations, transpile-time module composition, linalg stdlib). Phases 0–5 complete; see plan for current status.
+- `MANIFESTO-BUILDER.md` / `MANIFESTO-ENTERPRISE.md` — Positioning docs (audience-targeted pitches)
+- `benchmarks.md` — Top-level benchmark results (separate from `guides/benchmarks.md`)
 
-### Tracking Work
+### Keeping This File and `llms.txt` Current
 
-Work is tracked in plain markdown — no external issue tracker. Open items live in `TODO.md` (organized by area). When you start a task, find or add the relevant entry; when you finish, check the box and (for substantial work) move it to the Completed section with a short note.
+Update both files when you change something an agent needs to discover:
 
-### Landing the Plane (Session Completion Checklist)
+- **New top-level markdown doc** → add to "Additional Documentation" here AND to the appropriate section of `llms.txt`.
+- **New package entry point** (subpath export in `package.json`) → add to "Package Entry Points" here AND to "Package entry points" in `llms.txt`.
+- **New CLI command or `bun run` script** → add to "Common Commands".
+- **Renamed or moved key source file** → update "Key Source Files" here AND "Source map" in `llms.txt`.
+- **New language mode / safety directive** → add to the TJS Syntax Reference section.
+- **New playground example** → add to `guides/examples/{tjs,ajs}/<slug>.md`, then `bun run docs` to regenerate `demo/docs.json`. See "Playground Examples" above.
 
-When ending a work session that touched code, complete **all** steps below in order. Canonical version lives in `AGENTS.md`.
+Skip stale-prone precision (exact line counts, file sizes) for new entries — they drift silently. The existing `~3024` etc. are kept current opportunistically, not on every commit.
 
-1. **Update `TODO.md`** — check off completed items, add follow-ups for anything left undone, note blockers.
-2. **Run quality gates** — if code changed: `bun run format`, `bun run typecheck`, `bun run test:fast` (or `bun test` for full suite).
-3. **Commit** — focused commits with clear messages. Don't bundle unrelated changes.
-4. **Push to remote** — mandatory:
-   ```bash
-   git pull --rebase
-   git push
-   git status   # MUST show "up to date with 'origin/...'"
-   ```
-5. **Clean up** — clear stale stashes, prune merged remote branches if appropriate.
-6. **Verify** — working tree clean AND branch up to date with origin.
-7. **Hand off** — leave a brief summary so the next session can pick up cold.
+### Tracking Work
+
+Work is tracked in plain markdown — no external issue tracker. Open items live in `TODO.md` (organized by area). When you start a task, find or add the relevant entry; when you finish, check the box and (for substantial work) move it to the Completed section with a short note.
 
-**Hard rules:**
+### Landing the Plane (Session Completion Checklist)
 
-- Work is NOT complete until `git push` succeeds.
-- Never stop before pushing — leaving work stranded locally is leaving it lost.
-- Never say "ready to push when you are" — push it yourself.
-- If push fails, resolve the cause (rebase conflicts, hook failures, auth) and retry until it succeeds.
-- Never `--no-verify` to bypass hooks. Fix the underlying issue.
+See `AGENTS.md` for the canonical session-completion checklist. Hard rule: work is not complete until `git push` succeeds — never stop before pushing, never `--no-verify` to bypass hooks.
 
-### Known Gotcha: `tjs()` Returns an Object, Not a String
+### Common Gotchas
 
-`tjs(source)` returns `{ code, types, metadata, testResults, ... }`. Use `.code` to get the transpiled JavaScript string. This is a common mistake.
+- **`tjs(source)` returns an object, not a string.** It returns `{ code, types, metadata, testResults, ... }` — use `.code` for the transpiled JS string.
+- **Prettier mangles bare-expression code blocks in markdown.** Code blocks tagged ` ```js` get reformatted; bare expressions like `'5' == 5` and `[1] == 1` on consecutive lines collapse into one expression with ASI guards. Use `<!-- prettier-ignore -->` directly above the code fence to preserve hand-formatted JS examples (or tag the block as `text`/`tjs`/`ts` instead — Prettier ignores those).
+- **`tjs-lang` package alias only works inside the project** (set in `bunfig.toml`). Test scripts written in `/tmp` won't resolve `import { tjs } from 'tjs-lang/lang'` to the local source — they'll resolve to whatever's in `node_modules`. For ad-hoc experiments outside the repo, use absolute paths: `import { tjs } from '/Users/.../tjs-lang/src/lang/index'`.
 
 ### Running Emitted TJS Code
 

package/bin/docs.js

@@ -54,7 +54,10 @@ function extractDescription(content) {
 }
 
 function metadata(content, filePath) {
-  let source = content.match(/<\!\-\-(\{.*\})\-\->|\/\*(\{.*\})\*\//)
+  // Only the FIRST non-blank line may be frontmatter. Matching anywhere in
+  // the file produces false positives when docs document the format itself
+  // (e.g. CLAUDE.md showing an example of <!--{...}--> ).
+  let source = content.match(/^\s*(?:<\!\-\-(\{.*\})\-\->|\/\*(\{.*\})\*\/)/)
   let data = {}
   if (source) {
     try {