tjs-lang 0.8.7 → 0.9.1

package/CLAUDE.md

@@ -20,7 +20,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Development
 bun run format              # ESLint fix + Prettier
 bun run test:fast           # Core tests (skips LLM & benchmarks)
-bun run make                # Full build (clean, format, grammars, tsc, esbuild)
+bun run make                # Full build (clean, format, grammars, editors, tsc, esbuild)
+                            #   Named `make`, NOT `build`, on purpose: `bun build` is a Bun
+                            #   builtin (the bundler). If a `build` script existed, `bun build`
+                            #   would silently run the builtin instead of the script while
+                            #   `bun run build` ran the script — an ever-present footgun where
+                            #   the two commands diverge. Don't add a `build` script.
+bun run build:editors       # Bundle editors/{codemirror,monaco,ace}/*.ts → published *.js
 bun run dev                 # Development server with file watcher
 bun run start               # Build demo + start dev server
 bun run latest              # Clean reinstall (rm node_modules + bun install)
@@ -68,15 +74,15 @@ bun run functions:serve     # Local functions emulator
 ### Two-Layer Design
 
 1. **Builder Layer** (`src/builder.ts`): Fluent API that constructs AST nodes. Contains no execution logic.
-2. **Runtime Layer** (`src/vm/runtime.ts`): Executes AST nodes. Contains all atom implementations (~3024 lines, security-critical).
+2. **Runtime Layer** (`src/vm/runtime.ts`): Executes AST nodes. Contains all atom implementations (~3134 lines, security-critical).
 
 ### Key Source Files
 
 - `src/index.ts` - Main entry, re-exports everything
-- `src/vm/runtime.ts` - All atom implementations, expression evaluation, fuel charging (~3024 lines, security-critical)
+- `src/vm/runtime.ts` - All atom implementations, expression evaluation, fuel charging (~3134 lines, security-critical)
 - `src/vm/vm.ts` - AgentVM class (~247 lines)
 - `src/vm/atoms/batteries.ts` - Battery atoms (vector search, LLM, store operations)
-- `src/builder.ts` - TypedBuilder fluent API (~757 lines / ~19KB)
+- `src/builder.ts` - TypedBuilder fluent API (~754 lines / ~19KB)
 - `src/lang/parser.ts` - TJS parser with colon shorthand, unsafe markers, return type extraction
 - `src/lang/parser-transforms.ts` - Type, Generic, and FunctionPredicate block/function form transforms
 - `src/lang/emitters/ast.ts` - Emits Agent99 AST from parsed source
@@ -93,6 +99,8 @@ bun run functions:serve     # Local functions emulator
 - `src/lang/emitters/js-wasm.ts` - JS bootstrap emitter for compiled wasm modules (one `WebAssembly.compile` per file, name→export-index table, type-aware wrappers)
 - `src/lang/module-loader.ts` - Transpile-time `.tjs`/`.ts`/`.js` module loader (Phase 0.75); used by cross-file `wasm function` composition
 - `src/linalg/` - `tjs-lang/linalg` stdlib subpath (f32x4 SIMD vector kernels)
+- `src/schema/` - `tjs-lang/schema` subpath: **tosijs-schema pre-wired with `$predicate` support**. Re-exports the whole tosijs-schema surface and auto-registers `createPredicateEvaluator()` on import (batteries-included), so JSON-Schema validation is predicate-aware with zero wiring. Lives here (not in tosijs-schema) because tjs-lang depends on tosijs-schema — the reverse would be circular. `tosijs-schema` is externalized in the bundle (single instance → single global evaluator). Requires `tosijs-schema@^1.4.0` (the `setPredicateEvaluator` hook).
+- `src/css/` - `tjs-lang/css` subpath: CSS validators built from verified-safe predicates. `predicates.ts` (colors), `dimensions.ts` (lengths/numbers/angles/times/keywords), `shorthands.ts` (order-flexible `animation`/`transition` — paren-aware tokenize + classify), `style.ts` (recursive style-object structure + the `$predicate` JSON-Schema builders `cssStyleSchema`/`cssColorSchema`); `index.ts` = compiled validators + `suggestColor` + `verifyCss` (verifies all clusters). The predicate-types thesis made real — phases 1/2/3(animation+transition)/4 done; font/background shorthands + perf (phase 5) remain (TODO #4)
 - `src/types/` - Type system definitions (Type.ts, Generic.ts)
 - `src/transpiler/` - AJS transpiler (source → AST)
 - `src/batteries/` - LM Studio integration (lazy init, model audit, vector search)
@@ -146,6 +154,11 @@ 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
+import { isColor, suggestColor } from 'tjs-lang/css' // CSS validators (verified predicates)
+import { s, validate } from 'tjs-lang/schema' // tosijs-schema pre-wired with $predicate support
+import { createRuntime, Eq, isMonadicError } from 'tjs-lang/runtime' // TJS runtime (for emitted .tjs / integrations)
+// Bun: enable native .tjs imports — `preload = ["tjs-lang/bun-plugin"]` in bunfig.toml, or:
+import 'tjs-lang/bun-plugin' // registers the .tjs onLoad plugin + installs __tjs (bun-only)
 // Editor integrations: 'tjs-lang/editors/monaco', '/codemirror', '/ace'
 
 // Self-contained BROWSER bundles — drop-in via import() from any CDN, no
@@ -508,7 +521,8 @@ The CLI (`bun src/cli/tjs.ts run`) does NOT inject the test-block `expect` harne
 
 ### Additional Documentation
 
-- `PRINCIPLES.md` — **non-negotiable language invariants**: options-off TJS ⊇ JS, and TJS ⊇ AJS. A richer layer may do _more_ with the same source but must never make subset-legal code _illegal_ (e.g. un-runnable signature tests are inconclusive, not errors). Read before changing parser/transpiler acceptance or signature-test behavior; a subset violation is a bug.
+- `PRINCIPLES.md` — **non-negotiable language invariants**: options-off TJS ⊇ JS, and TJS ⊇ AJS. A richer layer may do _more_ with the same source but must never make subset-legal code _illegal_ (e.g. un-runnable signature tests are inconclusive, not errors). Read before changing parser/transpiler acceptance or signature-test behavior; a subset violation is a bug. Also carries the **type-system north star** (JSON-Schema + `$predicate` as the single source of truth for types — a decision lens).
+- `docs/type-system-north-star.md` — the north-star design note: JSON-Schema + `$predicate` as the canonical type representation; the decision lens ("closer to or further from?"); and the small portable predicate-VM (serialized-AST, cross-language) that unlocks it. Strategic (possibly post-1.0).
 - `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.

package/dist/experiments/ambient/probe.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Ambient-contract spike — the "derive" step in miniature.
+ *
+ * `deriveShapeContract(sample, name)` turns an observed value (a real object
+ * introspected from an ambient environment, or a synthetic stand-in) into a
+ * predicate-cluster SOURCE: presence + `typeof` checks per own key. Feed the
+ * source to `verifyPredicate`/`compilePredicate` and it's a certified, native,
+ * serializable contract for "looks like this thing". The real tool would source
+ * `sample` from a live browser probe (Claude-in-Chrome / the introspection
+ * iframe) and scope it to the surface a program actually uses; this is just the
+ * transform, so the whole loop is testable headlessly.
+ *
+ * See docs/ambient-contracts.md.
+ */
+/** A single derived check line. */
+type Check = {
+    key: string;
+    type: string;
+    kind: 'value' | 'method';
+};
+export interface ProbeOptions {
+    /**
+     * Only probe these keys. STRONGLY recommended for host objects: the surface a
+     * program actually uses, traced from the real environment. Without it we walk
+     * the whole prototype chain, which for a DOM object is hundreds of props — a
+     * huge, over-specified contract.
+     */
+    keys?: string[];
+    /** How many prototype levels to walk when `keys` is not given. Default 3. */
+    maxDepth?: number;
+}
+/**
+ * Introspect a sample's shape → (key, typeof, method?) checks.
+ *
+ * Host objects (DOM etc.) hide their real surface on the PROTOTYPE, non-
+ * enumerable — `Object.keys(element.style)` is nearly empty even though
+ * `typeof style.color === 'string'`. So we walk the prototype chain (or check a
+ * scoped `keys` list) and read `typeof sample[key]`, not `Object.keys`.
+ *
+ * Caveat (noted in docs/ambient-contracts.md): reading an accessor invokes its
+ * getter, which on a real DOM object can have side effects (e.g. `offsetWidth`
+ * forces layout). A scoped `keys` list keeps this bounded; a stricter probe would
+ * inspect property descriptors instead of reading. Getters that throw are skipped.
+ */
+export declare function probeShape(sample: Record<string, unknown>, opts?: ProbeOptions): Check[];
+/**
+ * Emit a predicate-safe source cluster asserting `x` has the probed shape:
+ * non-null, and each key present with the observed `typeof`. The last function
+ * (`is<Name>`) is the entry, so the source drops straight into a `$predicate`.
+ */
+export declare function deriveShapeContract(sample: Record<string, unknown>, name: string, opts?: ProbeOptions): string;
+export {};