tosijs-ui 1.6.21 → 1.7.0-beta.1

package/dist/live-example/code-transform.d.ts

@@ -18,6 +18,45 @@ export declare function contextVarName(key: string): string;
  * the AsyncFunction body.
  */
 export declare function rewriteImports(code: string, contextKeys: string[]): string;
+/**
+ * Blank out the CONTENTS of strings, template literals, comments and regex literals,
+ * preserving length and newlines so every index still lines up with the original.
+ *
+ * The scanner below counts brackets and matches `^const` over raw text, which made it
+ * wrong in two ways that both failed silently:
+ *
+ *   const label = 'Items ('      → an unbalanced '(' inside a string ran the depth
+ *                                  counter away, swallowing the REST OF THE FILE, so
+ *                                  every later binding vanished from completions.
+ *   `const in a template`        → matched at column 0 inside a template literal and
+ *                                  yielded the name `in`, and the epilogue then emitted
+ *                                  `try{__tosiScope.in=in}` — a PARSE error, which no
+ *                                  try/catch can absorb, killing the whole example.
+ *
+ * Identifiers never live inside literals, so masking loses nothing we want.
+ */
+export declare function maskLiterals(code: string): string;
+/**
+ * Best-effort list of the identifiers a snippet binds at the TOP level (column 0, so
+ * genuinely function-scope, not inside a block). Handles `const/let/var` — including
+ * MULTI-LINE destructuring, MULTIPLE declarators (`const a = 1, b = 2`), nested
+ * patterns, aliases, defaults and rest — plus `function`/`class` declarations.
+ *
+ * This is a scanner, not a parse. tjs-lang already owns an acorn-based
+ * `collectScopeSymbols()` that does this properly, but it has no public export
+ * (filed upstream); when it lands, drive this off it. Meanwhile imperfect is safe:
+ * the capture epilogue guards every name individually, so an over- or under-match
+ * degrades completions rather than breaking the example.
+ */
+export declare function extractTopLevelBindingNames(code: string): string[];
+/**
+ * Build an epilogue that captures the values of `names` (as they stand at the end
+ * of a run) into `captureVar(scopeObject)`. Each binding is read behind its own
+ * try/catch so a stale/over-matched name can't abort the whole capture, and the
+ * whole thing is a trailing block so it never shadows user code. Returns '' when
+ * there's nothing to capture.
+ */
+export declare function buildScopeCapture(names: string[], captureVar: string): string;
 /**
  * Execute code as an async function with injected context
  */

package/dist/live-example/code-transform.js

@@ -41,6 +41,302 @@ export function rewriteImports(code, contextKeys) {
     }
     return result;
 }
+const OPEN = '([{';
+const CLOSE = ')]}';
+/** Index of the first `ch` at bracket depth 0, or -1. */
+function indexAtDepth0(src, ch) {
+    let depth = 0;
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (OPEN.includes(c))
+            depth++;
+        else if (CLOSE.includes(c))
+            depth--;
+        else if (c === ch && depth === 0) {
+            if (ch === '=') {
+                // Only a bare assignment counts — skip ==, =>, <=, >=, !=.
+                const next = src[i + 1];
+                const prev = src[i - 1];
+                if (next === '=' || next === '>' || (prev && '=!<>'.includes(prev)))
+                    continue;
+            }
+            return i;
+        }
+    }
+    return -1;
+}
+/** Split on `,` at bracket depth 0, so nested commas (`{ a: { b, c } }`) don't split. */
+function splitAtDepth0(src) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (OPEN.includes(c))
+            depth++;
+        else if (CLOSE.includes(c))
+            depth--;
+        else if (c === ',' && depth === 0) {
+            parts.push(src.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(src.slice(start));
+    return parts.filter((p) => p.trim() !== '');
+}
+/**
+ * Blank out the CONTENTS of strings, template literals, comments and regex literals,
+ * preserving length and newlines so every index still lines up with the original.
+ *
+ * The scanner below counts brackets and matches `^const` over raw text, which made it
+ * wrong in two ways that both failed silently:
+ *
+ *   const label = 'Items ('      → an unbalanced '(' inside a string ran the depth
+ *                                  counter away, swallowing the REST OF THE FILE, so
+ *                                  every later binding vanished from completions.
+ *   `const in a template`        → matched at column 0 inside a template literal and
+ *                                  yielded the name `in`, and the epilogue then emitted
+ *                                  `try{__tosiScope.in=in}` — a PARSE error, which no
+ *                                  try/catch can absorb, killing the whole example.
+ *
+ * Identifiers never live inside literals, so masking loses nothing we want.
+ */
+export function maskLiterals(code) {
+    const out = code.split('');
+    const blank = (from, to) => {
+        for (let i = from; i < to && i < out.length; i++) {
+            if (out[i] !== '\n')
+                out[i] = ' ';
+        }
+    };
+    // A `/` starts a regex (not division) only where a value can't precede it.
+    const regexAllowedAfter = /[=(,:[!&|?{};+\-*%~^<>]$/;
+    let i = 0;
+    while (i < code.length) {
+        const c = code[i];
+        const next = code[i + 1];
+        if (c === '/' && next === '/') {
+            const end = code.indexOf('\n', i);
+            blank(i, end === -1 ? code.length : end);
+            i = end === -1 ? code.length : end;
+        }
+        else if (c === '/' && next === '*') {
+            const end = code.indexOf('*/', i + 2);
+            blank(i, end === -1 ? code.length : end + 2);
+            i = end === -1 ? code.length : end + 2;
+        }
+        else if (c === "'" || c === '"') {
+            let j = i + 1;
+            while (j < code.length && code[j] !== c) {
+                if (code[j] === '\\')
+                    j++;
+                if (code[j] === '\n')
+                    break; // unterminated — don't run away
+                j++;
+            }
+            blank(i + 1, j); // keep the quotes — see NB below
+            i = j + 1;
+        }
+        else if (c === '`') {
+            // Template literal: skip to the matching backtick, stepping over ${…} (which can
+            // nest braces and contain more backticks).
+            let j = i + 1;
+            let braces = 0;
+            while (j < code.length) {
+                if (code[j] === '\\')
+                    j += 2;
+                else if (braces === 0 && code[j] === '`')
+                    break;
+                else if (code[j] === '$' && code[j + 1] === '{') {
+                    braces++;
+                    j += 2;
+                }
+                else if (braces > 0 && code[j] === '{') {
+                    braces++;
+                    j++;
+                }
+                else if (braces > 0 && code[j] === '}') {
+                    braces--;
+                    j++;
+                }
+                else
+                    j++;
+            }
+            blank(i + 1, j); // keep the backticks
+            i = j + 1;
+        }
+        else if (c === '/') {
+            const before = code.slice(0, i).replace(/\s+$/, '');
+            if (before === '' || regexAllowedAfter.test(before)) {
+                let j = i + 1;
+                let inClass = false;
+                while (j < code.length) {
+                    if (code[j] === '\\')
+                        j++;
+                    else if (code[j] === '[')
+                        inClass = true;
+                    else if (code[j] === ']')
+                        inClass = false;
+                    else if (code[j] === '/' && !inClass)
+                        break;
+                    else if (code[j] === '\n')
+                        break; // unterminated — it was division after all
+                    j++;
+                }
+                blank(i + 1, j); // keep the slashes
+                i = j + 1;
+            }
+            else
+                i++; // division
+        }
+        else
+            i++;
+    }
+    return out.join('');
+}
+// Reserved words are identifier-SHAPED but can't be read as one: emitting
+// `try{__tosiScope.in=in}` is a SyntaxError that no try/catch absorbs, and it takes the
+// whole example down with it. Masking should already prevent these from being matched;
+// this is the belt to that suspenders.
+const RESERVED = new Set(('break case catch class const continue debugger default delete do else enum export ' +
+    'extends false finally for function if import in instanceof new null return super ' +
+    'switch this throw true try typeof var void while with yield let static implements ' +
+    'interface package private protected public await').split(' '));
+const isCapturableName = (name) => /^[A-Za-z_$][\w$]*$/.test(name) && !RESERVED.has(name);
+/** Pull the bound identifiers out of one declaration's left-hand side. */
+function patternNames(lhs) {
+    lhs = lhs.trim();
+    if (!lhs)
+        return [];
+    if (/^[{[]/.test(lhs)) {
+        // Object/array destructuring. Split depth-0 commas (NOT a naive `split(',')`,
+        // which shreds `{ a: { b, c } }`), then per element: drop a rest `...`, take the
+        // TARGET of `key: target` (the target is what's bound, and may itself be a
+        // pattern), drop any `= default`, and recurse into nested patterns.
+        const names = [];
+        for (let part of splitAtDepth0(lhs.slice(1, -1))) {
+            part = part.trim().replace(/^\.\.\./, '');
+            if (!part)
+                continue;
+            const colon = indexAtDepth0(part, ':');
+            if (colon !== -1)
+                part = part.slice(colon + 1).trim();
+            const eq = indexAtDepth0(part, '=');
+            if (eq !== -1)
+                part = part.slice(0, eq).trim();
+            if (/^[{[]/.test(part)) {
+                names.push(...patternNames(part));
+            }
+            else {
+                const m = part.match(/^[A-Za-z_$][\w$]*/);
+                if (m)
+                    names.push(m[0]);
+            }
+        }
+        return names;
+    }
+    const m = lhs.match(/^[A-Za-z_$][\w$]*/);
+    return m ? [m[0]] : [];
+}
+/**
+ * Read a `const/let/var` declaration starting at `from` — across newlines, so a
+ * wrapped destructure (`const {\n  app,\n} = …`) is captured whole. Ends at a depth-0
+ * `;`, or at a newline where the statement is plainly complete (the previous
+ * non-space char isn't an operator/comma continuing it). Anything unbalanced keeps
+ * reading, because depth > 0.
+ */
+function readDeclaration(code, from) {
+    let depth = 0;
+    let i = from;
+    for (; i < code.length; i++) {
+        const c = code[i];
+        if (OPEN.includes(c))
+            depth++;
+        else if (CLOSE.includes(c))
+            depth--;
+        else if (depth === 0 && c === ';')
+            break;
+        else if (depth === 0 && c === '\n') {
+            const soFar = code.slice(from, i).trimEnd();
+            const last = soFar[soFar.length - 1];
+            if (last !== undefined && !',=+-*/%&|?:<>!~^'.includes(last))
+                break;
+        }
+    }
+    // FAIL SAFE. Running to EOF with depth > 0 means the brackets never balanced, and
+    // consuming the tail would silently drop every binding after this point (the old
+    // behaviour, and the whole bug). Masking should make this unreachable; if it happens
+    // anyway, give up on THIS declaration only — take the first line and let the scan
+    // resume — rather than swallowing the rest of the example.
+    if (i >= code.length && depth > 0) {
+        const eol = code.indexOf('\n', from);
+        return code.slice(from, eol === -1 ? code.length : eol);
+    }
+    return code.slice(from, i);
+}
+/**
+ * Best-effort list of the identifiers a snippet binds at the TOP level (column 0, so
+ * genuinely function-scope, not inside a block). Handles `const/let/var` — including
+ * MULTI-LINE destructuring, MULTIPLE declarators (`const a = 1, b = 2`), nested
+ * patterns, aliases, defaults and rest — plus `function`/`class` declarations.
+ *
+ * This is a scanner, not a parse. tjs-lang already owns an acorn-based
+ * `collectScopeSymbols()` that does this properly, but it has no public export
+ * (filed upstream); when it lands, drive this off it. Meanwhile imperfect is safe:
+ * the capture epilogue guards every name individually, so an over- or under-match
+ * degrades completions rather than breaking the example.
+ */
+export function extractTopLevelBindingNames(code) {
+    // Scan MASKED source: literals and comments are blanked (same length, same newlines),
+    // so a stray bracket or a `const` inside a string can't derail the scan. Indices still
+    // line up with `code`, and identifiers only ever live outside literals.
+    const masked = maskLiterals(code);
+    const names = new Set();
+    const declRe = /^(?:export\s+)?(const|let|var|function\*?|class)\s+/gm;
+    let m;
+    while ((m = declRe.exec(masked)) !== null) {
+        const kind = m[1];
+        const from = m.index + m[0].length;
+        if (kind === 'class' || kind.startsWith('function')) {
+            const id = masked.slice(from).match(/^[A-Za-z_$][\w$]*/);
+            if (id)
+                names.add(id[0]);
+            continue;
+        }
+        const decl = readDeclaration(masked, from);
+        // Each depth-0 comma starts another declarator (`const a = 1, b = 2`).
+        for (const declarator of splitAtDepth0(decl)) {
+            const eq = indexAtDepth0(declarator, '=');
+            const lhs = eq === -1 ? declarator : declarator.slice(0, eq);
+            for (const n of patternNames(lhs))
+                names.add(n);
+        }
+        // Don't rescan inside the declaration we just consumed.
+        declRe.lastIndex = from + decl.length;
+    }
+    return [...names].filter(isCapturableName);
+}
+/**
+ * Build an epilogue that captures the values of `names` (as they stand at the end
+ * of a run) into `captureVar(scopeObject)`. Each binding is read behind its own
+ * try/catch so a stale/over-matched name can't abort the whole capture, and the
+ * whole thing is a trailing block so it never shadows user code. Returns '' when
+ * there's nothing to capture.
+ */
+export function buildScopeCapture(names, captureVar) {
+    // Filter HERE too, not just at extraction. Every other guard in this file is a
+    // runtime try/catch, but an unreadable name (`in`, `class`, `2bad`) makes the
+    // epilogue itself unparseable — and a SyntaxError takes the whole example down
+    // before a single line of it runs. This is the last line of defence, so it must not
+    // trust its caller.
+    const capturable = names.filter(isCapturableName);
+    if (capturable.length === 0)
+        return '';
+    const assigns = capturable
+        .map((n) => `try{__tosiScope.${n}=${n}}catch(_e){}`)
+        .join('');
+    return `\n;{const __tosiScope={};${assigns}${captureVar}(__tosiScope)}`;
+}
 /**
  * Execute code as an async function with injected context
  */
@@ -61,7 +357,7 @@ export async function executeCode(code, context, transform) {
 // self-contained) and is loaded only for `ts` examples; from-ts in turn fetches
 // the TypeScript compiler lazily at runtime, so tsc is never pulled in until a TS
 // example actually transforms. Pinned to match the dev dep.
-const TJS_VERSION = '0.9.0';
+const TJS_VERSION = '0.9.1';
 // Where to fetch a tjs-lang browser bundle from, in priority order:
 //  1. SAME-ORIGIN — the doc-site build copies the bundles next to the iife and
 //     sets `__TJS_LOCAL_BASE`, so the transpiler ships in lockstep with the page,
@@ -71,7 +367,8 @@ const TJS_VERSION = '0.9.0';
 //     it (minutes–hours) and any one can blip, so we try several. The module-cache
 //     service worker caches all three hosts.
 function bundleUrls(file) {
-    const localBase = globalThis.__TJS_LOCAL_BASE;
+    const localBase = globalThis
+        .__TJS_LOCAL_BASE;
     return [
         ...(typeof localBase === 'string' ? [`${localBase}${file}`] : []),
         `https://cdn.jsdelivr.net/npm/tjs-lang@${TJS_VERSION}/dist/${file}`,
@@ -119,7 +416,9 @@ async function loadTjsTestApiImpl() {
     for (const load of sources) {
         try {
             const m = (await load());
-            if (m && typeof m.extractTests === 'function' && typeof m.testUtils === 'string') {
+            if (m &&
+                typeof m.extractTests === 'function' &&
+                typeof m.testUtils === 'string') {
                 return { extractTests: m.extractTests, testUtils: m.testUtils };
             }
         }
@@ -202,7 +501,9 @@ export async function loadTransform(dialect = 'js') {
         if (dialect === 'ts') {
             // async: fromTS lazy-loads the TypeScript compiler on first use.
             return (async () => {
-                const tjsSource = fromTS ? (await fromTS(code, { emitTJS: true })).code : code;
+                const tjsSource = fromTS
+                    ? (await fromTS(code, { emitTJS: true })).code
+                    : code;
                 const result = {
                     code: tjs(tjsSource, { dialect: 'tjs', runTests: false }).code,
                 };

package/dist/live-example/component.d.ts

@@ -227,6 +227,7 @@ export declare class LiveExample extends Component<ExampleParts> {
     prefix: string;
     storageKey: string;
     context: ExampleContext;
+    private capturedScope;
     uuid: string;
     remoteId: string;
     private remoteSync?;
@@ -262,6 +263,15 @@ export declare class LiveExample extends Component<ExampleParts> {
     private renderTjsTests;
     private computeGeneratedJs;
     private ensureProductTabs;
+    private captureScope;
+    /**
+     * Live bindings for tjs runtime-value autocomplete: the example's context modules
+     * (keyed by the identifier the rewritten code uses, e.g. `tosijs`, `tosijsui`),
+     * the currently-rendered `preview` element, and the latest run's top-level locals
+     * (so `const app = tosi(…)` gives real `app.` / `app.items.` completions, proxy
+     * members and all). Read lazily on each completion, so it reflects the latest run.
+     */
+    private liveBindings;
     updateUndo: () => void;
     private updateTestResultsVisibility;
     undo: () => void;

package/dist/live-example/component.js

@@ -162,10 +162,22 @@ function step(! px: Float32Array, py: Float32Array, vx: Float32Array, vy: Float3
   }
 }
 
-const W = 480, H = 300, cols = 100, rows = 60, N = cols * rows
-const px = new Float32Array(N), py = new Float32Array(N)
-const vx = new Float32Array(N), vy = new Float32Array(N)
-const hx = new Float32Array(N), hy = new Float32Array(N)
+// 100k particles, not 6k. At 6k each step took ~0.02ms — right at the resolution floor
+// of performance.now(), so the readout was mostly measuring the timer. At this size both
+// paths land in the hundreds of microseconds and the comparison actually means something.
+const W = 480, H = 300, cols = 400, rows = 250, N = cols * rows
+
+// Allocate the particle arrays INSIDE wasm memory. This is the whole ballgame: if a
+// typed array's buffer isn't the wasm memory, every call copies it in and out again —
+// six 6,000-float arrays per frame — and you end up timing memcpy, not SIMD. (With
+// plain `new Float32Array(N)` this demo measured ~4x SLOWER than its own JS fallback.)
+// `wasmBuffer` is a bump allocator handing out views into the shared wasm memory, so
+// the wrapper passes a byte offset and copies nothing. Fall back gracefully if the
+// wasm block didn't compile, so the JS twin still runs.
+const f32 = (n) => globalThis.wasmBuffer ? wasmBuffer(Float32Array, n) : new Float32Array(n)
+const px = f32(N), py = f32(N)
+const vx = f32(N), vy = f32(N)
+const hx = f32(N), hy = f32(N)
 for (let i = 0; i < N; i++) {
   const c = i % cols, r = (i / cols) | 0
   hx[i] = (c + 0.5) * W / cols
@@ -180,6 +192,15 @@ canvas.height = H
 canvas.style.cssText = 'width:100%;max-width:480px;border-radius:8px;display:block;background:#0b0e14;touch-action:none;cursor:crosshair'
 const ctx = canvas.getContext('2d')
 
+// Plot straight into an ImageData buffer (one 32-bit store per particle) instead of
+// 100k fillRect() calls — otherwise the DRAW would dominate and we'd be benchmarking
+// canvas, not the kernel.
+const img = ctx.createImageData(W, H)
+const pix = new Uint32Array(img.data.buffer)
+const BG = 0xff140e0b        // #0b0e14, little-endian ABGR
+const TEAL = 0xffc5d14f      // #4fd1c5
+const AMBER = 0xff55adf6     // #f6ad55
+
 let tx = W / 2, ty = H / 2, idle = 0, frame = 0
 canvas.addEventListener('pointermove', (e) => {
   const r = canvas.getBoundingClientRect()
@@ -188,21 +209,35 @@ canvas.addEventListener('pointermove', (e) => {
   idle = 0
 })
 
-// tjs registers the compiled function as globalThis.__tjs_wasm_0; nulling it makes
-// step() fall to its JS twin. (A public WASM on/off toggle would be tidier — noted
-// in TJS-FEEDBACK.md.)
-let useWasm = true, savedWasm = null
+// tjs-lang 0.9.1+ gates every wasm call on `globalThis.__tjs_wasm_enabled`, so this
+// flips the kernel between WASM and its JS twin without touching tjs internals.
+// (Don't reach for `__tjs_wasm_0` — it's private AND index-keyed per transpile, so
+// a second wasm example on the page registers the same name and you'd clobber it.)
+let useWasm = true
 const btn = document.createElement('button')
 btn.style.cssText = 'margin:8px 0;padding:6px 12px;border-radius:6px;cursor:pointer'
 const readout = document.createElement('p')
+let acc = 0, frames = 0
 function applyMode() {
-  if (useWasm && savedWasm) { globalThis.__tjs_wasm_0 = savedWasm; savedWasm = null }
-  if (!useWasm && globalThis.__tjs_wasm_0) { savedWasm = globalThis.__tjs_wasm_0; globalThis.__tjs_wasm_0 = null }
+  globalThis.__tjs_wasm_enabled = useWasm
+  acc = 0; frames = 0 // don't average across a mode switch
   btn.textContent = useWasm ? '⚡ WebAssembly SIMD — click for JavaScript' : '🐢 JavaScript — click for WASM SIMD'
 }
 btn.onclick = () => { useWasm = !useWasm; applyMode() }
 
-let acc = 0, frames = 0
+// Warm BOTH paths before timing anything. The JS twin never executes until you click
+// over to it, so an un-warmed comparison times cold, un-JITed JavaScript and flatters
+// WASM (it read ~2x too good). A warmed V8 does this kernel in ~0.024 ms/step; the
+// zero-copy SIMD kernel does ~0.015 — a real but modest ~1.6x, which is the honest
+// number this demo should show.
+function warmUp() {
+  for (const on of [false, true]) {
+    globalThis.__tjs_wasm_enabled = on
+    for (let i = 0; i < 150; i++) step(px, py, vx, vy, hx, hy, N, W / 2, H / 2)
+  }
+  // the warm-up perturbed the particles — put them back on the grid
+  for (let i = 0; i < N; i++) { px[i] = hx[i]; py[i] = hy[i]; vx[i] = 0; vy[i] = 0 }
+}
 function loop() {
   if (!document.body.contains(canvas)) return // example removed → stop
   frame++
@@ -215,10 +250,15 @@ function loop() {
   step(px, py, vx, vy, hx, hy, N, tx, ty)
   acc += performance.now() - t0
   frames++
-  ctx.fillStyle = 'rgba(11,14,20,0.3)'
-  ctx.fillRect(0, 0, W, H)
-  ctx.fillStyle = useWasm ? '#4fd1c5' : '#f6ad55'
-  for (let i = 0; i < N; i++) ctx.fillRect(px[i], py[i], 1.6, 1.6)
+
+  pix.fill(BG)
+  const dot = useWasm ? TEAL : AMBER
+  for (let i = 0; i < N; i++) {
+    const x = px[i] | 0, y = py[i] | 0
+    if (x >= 0 && x < W && y >= 0 && y < H) pix[y * W + x] = dot
+  }
+  ctx.putImageData(img, 0, 0)
+
   if (frames >= 20) {
     readout.textContent = N.toLocaleString() + ' particles · ' + (acc / frames).toFixed(3) +
       ' ms/step (' + (useWasm ? 'WASM SIMD' : 'JS') + ') · move the pointer'
@@ -229,12 +269,11 @@ function loop() {
 }
 
 ;(async () => {
-  // The wasm bootstrap is async — wait for the compiled function before starting,
-  // so the first frames run in WASM rather than the fallback.
-  const t0 = performance.now()
-  while (!globalThis.__tjs_wasm_0 && performance.now() - t0 < 3000) {
-    await new Promise((r) => setTimeout(r, 0))
-  }
+  // The wasm bootstrap is async. tjs-lang 0.9.1+ exposes an awaitable ready signal,
+  // so we start only once the kernel is instantiated — otherwise the first frames
+  // silently run the JS fallback while the button claims "WebAssembly SIMD".
+  await globalThis.__tjs_wasm_ready?.()
+  warmUp()
   applyMode()
   requestAnimationFrame(loop)
 })()
@@ -242,6 +281,17 @@ function loop() {
 preview.append(canvas, btn, readout)
 ```
 
+```test
+// Guard the claim the button makes. A `wasm {}` block that fails to compile falls
+// back to JS *silently*, so without this the demo can advertise "⚡ WebAssembly SIMD"
+// while running the JS twin, and every test stays green.
+test('the wasm kernel actually compiled (no silent fallback to JS)', async () => {
+  await globalThis.__tjs_wasm_ready?.()
+  expect(typeof globalThis.__tjs_wasm_ready).toBe('function')
+  expect(globalThis.__tjs_wasm_0).toBeTruthy()
+})
+```
+
 ## CSS Isolation with `iframe`
 
 Add the `iframe` attribute to render the preview inside an iframe, giving the example
@@ -417,6 +467,9 @@ export class LiveExample extends Component {
     prefix = 'lx';
     storageKey = STORAGE_KEY;
     context = {};
+    // The example's top-level locals from the latest run, captured in-run for tjs
+    // runtime-value autocomplete (see `liveBindings`). Populated via `onScope`.
+    capturedScope = {};
     uuid = crypto.randomUUID();
     remoteId = '';
     remoteSync;
@@ -602,6 +655,11 @@ export class LiveExample extends Component {
         // put the source editor in the dialect's mode — so a `tjs` example gets
         // first-class tjs editing (highlighting + autocomplete), `ts` gets TypeScript.
         this.parts.js.setAttribute('name', this.dialect);
+        // Runtime-value autocomplete: give the tjs completion source the example's live
+        // bindings (context modules + the rendered preview) so it can suggest their REAL
+        // members — including tosijs proxy members that static analysis can't see. Set
+        // before `.mode` so the tjs extension loads with the config in one shot.
+        this.parts.js.tjsAutocomplete = { getLiveBindings: () => this.liveBindings() };
         this.parts.js.mode = this.dialect;
         this.jsOutEditor = codeEditor({
             name: 'JS',
@@ -619,6 +677,30 @@ export class LiveExample extends Component {
         this.jsOutEditor.value = this.lastGeneratedJs;
         this.renderTjsTests();
     }
+    // Capture the latest run's top-level locals (arrow property so `this` is bound
+    // when passed as execution's `onScope`).
+    captureScope = (scope) => {
+        this.capturedScope = scope;
+    };
+    /**
+     * Live bindings for tjs runtime-value autocomplete: the example's context modules
+     * (keyed by the identifier the rewritten code uses, e.g. `tosijs`, `tosijsui`),
+     * the currently-rendered `preview` element, and the latest run's top-level locals
+     * (so `const app = tosi(…)` gives real `app.` / `app.items.` completions, proxy
+     * members and all). Read lazily on each completion, so it reflects the latest run.
+     */
+    liveBindings() {
+        const bindings = {};
+        for (const [key, value] of Object.entries(this.context)) {
+            bindings[contextVarName(key)] = value;
+        }
+        const preview = this.parts.example?.querySelector('.preview');
+        if (preview)
+            bindings.preview = preview;
+        // Run locals last so they win over same-named context entries.
+        Object.assign(bindings, this.capturedScope);
+        return bindings;
+    }
     updateUndo = () => {
         const { activeTab } = this;
         const { undo, redo } = this.parts;
@@ -1201,6 +1283,7 @@ export class LiveExample extends Component {
                 exampleElement: example,
                 widgetsElement: exampleWidgets,
                 onError,
+                onScope: this.captureScope,
             });
         }
         else {
@@ -1214,6 +1297,7 @@ export class LiveExample extends Component {
                 styleElement: styleEl,
                 widgetsElement: exampleWidgets,
                 onError,
+                onScope: this.captureScope,
             });
         }
         if (this.persistToDom) {

package/dist/live-example/execution.d.ts

@@ -15,7 +15,23 @@ export interface ExecutionOptions {
     context: ExampleContext;
     transform: TransformFn;
     onError?: (error: Error) => void;
+    /**
+     * Receives the example's top-level locals after a successful run, so tjs
+     * autocomplete can introspect the REAL values (e.g. a `const app = tosi(…)`
+     * proxy) the user just created. Captured in-run — no re-execution, so no
+     * doubled side effects.
+     */
+    onScope?: (scope: Record<string, unknown>) => void;
 }
+/**
+ * Append a scope-capture epilogue to already-transformed example code when a
+ * consumer wants the run's locals. Returns the (possibly unchanged) code plus the
+ * extra context entry to inject. The epilogue no-ops if the example binds nothing.
+ */
+export declare function withScopeCapture(transformedCode: string, onScope?: (scope: Record<string, unknown>) => void): {
+    code: string;
+    extraContext: Record<string, unknown>;
+};
 /**
  * Execute code inline (directly in the page)
  */