@kernlang/terminal 3.2.3 → 3.3.4

package/dist/transpiler-ink.js

@@ -3,7 +3,7 @@ import { accountNode, buildDiagnostics, countTokens, dedent, generateCoreNode, g
  * Ink Transpiler — generates React (Ink) TSX components for terminal UIs
  *
  * Maps KERN terminal nodes to Ink components:
- *   screen  → React function component (export default)
+ *   screen  → React function component (named export by default, default export when requested)
  *   text    → <Text bold color="blue">...</Text>
  *   box     → <Box borderStyle="round" borderColor="blue">...</Box>
  *   separator → <Text dimColor>{'─'.repeat(48)}</Text>
@@ -28,6 +28,16 @@ import { accountNode, buildDiagnostics, countTokens, dedent, generateCoreNode, g
 function capitalize(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }
+function inkScreenExportKeyword(exportAttr) {
+    if (exportAttr === false || exportAttr === 'false')
+        return '';
+    return exportAttr === 'default' ? 'export default' : 'export';
+}
+function inkScreenExportStatement(exportKw, symbol) {
+    if (!exportKw)
+        return null;
+    return exportKw === 'export default' ? `export default ${symbol};` : `export { ${symbol} };`;
+}
 /** Check if a prop value is a {{ expression }} object from the parser. */
 function isExpr(v) {
     return typeof v === 'object' && v !== null && '__expr' in v;
@@ -118,6 +128,7 @@ class ImportTracker {
     reactImports = new Set();
     inkImports = new Set();
     inkUIImports = new Set();
+    kernRuntimeImports = new Set();
     addReact(name) {
         this.reactImports.add(name);
     }
@@ -128,6 +139,10 @@ class ImportTracker {
     addInkUI(name) {
         this.inkUIImports.add(name);
     }
+    /** Add a component from @kernlang/terminal/runtime. */
+    addKernRuntime(name) {
+        this.kernRuntimeImports.add(name);
+    }
     // Legacy convenience methods — now route to @inkjs/ui
     needSpinner() {
         this.inkUIImports.add('Spinner');
@@ -152,6 +167,9 @@ class ImportTracker {
         if (this.inkUIImports.size > 0) {
             lines.push(`import { ${[...this.inkUIImports].sort().join(', ')} } from '@inkjs/ui';`);
         }
+        if (this.kernRuntimeImports.size > 0) {
+            lines.push(`import { ${[...this.kernRuntimeImports].sort().join(', ')} } from '@kernlang/terminal/runtime';`);
+        }
         return lines;
     }
 }
@@ -189,6 +207,7 @@ function generateStateHook(stateNode, imports, ctx) {
     const name = props.name;
     const initialProp = props.initial;
     const safe = props.safe !== 'false' && props.safe !== false; // default true
+    const external = props.external === 'true' || props.external === true;
     if (name && initialProp !== undefined) {
         imports.addReact('useState');
         const initial = isExpr(initialProp) ? initialProp.code : String(initialProp);
@@ -217,6 +236,36 @@ function generateStateHook(stateNode, imports, ctx) {
         const lazyInitVal = needsLazyInit(initVal, props.type) ? `() => ${initVal}` : initVal;
         const throttle = props.throttle;
         const debounce = props.debounce;
+        if (external) {
+            // External-state primitive: a stable reference whose internal mutations
+            // are tracked via a sibling version counter. Replaces the manual
+            // `state foo + state fooVersion + setFooVersion(v => v + 1)` pattern.
+            // The held value is emitted as a bare useState (no __inkSafe wrap — the
+            // user mutates the object in place; the rare full-replacement case is
+            // a sync setState that React 18 batches inside event handlers). The
+            // version counter is hidden; the user calls `bumpFoo()` after mutating
+            // the object, and any memo that references `foo` automatically gets
+            // `_fooVersion` injected into its dep array.
+            if (throttle !== undefined || debounce !== undefined) {
+                throw new Error(`state '${name}' uses external=true with throttle/debounce, which are mutually exclusive. ` +
+                    `External state holds a stable reference; throttle/debounce apply to setter call rates and have no meaning ` +
+                    `here. Drop one of the two, or split into a separate state node if you really need both.`);
+            }
+            if (props.safe === 'false' || props.safe === false) {
+                throw new Error(`state '${name}' uses external=true with safe=false. External state already emits a bare useState (the safe wrapper does not apply), so safe=false is redundant — and combining them suggests a misunderstanding. Drop safe=false.`);
+            }
+            imports.addReact('useMemo');
+            const cap = capitalize(name);
+            lines.push(`  const [${name}, ${setter}] = useState${typeAnnotation}(${lazyInitVal});`);
+            lines.push(`  const [_${name}Version, _set${cap}VersionRaw] = useState<number>(0);`);
+            lines.push(`  const bump${cap} = useMemo(() => {`);
+            lines.push(`    return () => setTimeout(() => _set${cap}VersionRaw((v: number) => v + 1), 0);`);
+            lines.push(`  }, []);`);
+            // Touch the version in the closure so React picks it up if the user references
+            // it directly. The void cast keeps the lint quiet about an unused binding.
+            lines.push(`  void _${name}Version;`);
+            return lines;
+        }
         if (throttle) {
             // Throttled setter — leading+trailing by default (lodash-style).
             // trailing=false reverts to leading-only (drops intermediate + final values in window).
@@ -511,10 +560,101 @@ function collectNestedOnNodes(node) {
 }
 // ── Generate useInput from an on-node ───────────────────────────────────
 let _onHookCounter = 0;
-function generateOnHook(onNode, imports) {
+/**
+ * Rewrite a handler body so that every `setX(...)` call against a known safe state
+ * is replaced with the corresponding raw setter `_setXRaw(...)`. Used by batched
+ * handlers to bypass the per-setter __inkSafe macrotask deferral, so the whole
+ * batch can share a single deferred macrotask.
+ *
+ * The match uses a negative lookbehind so it only fires on bare setter calls.
+ * `form.setCount(...)` and any locally-shadowed `const setCount = ...; setCount(...)`
+ * preceded by a member access or word char are NOT rewritten.
+ *
+ * Limitation: substitution is text-based, so a setter name appearing as a bare
+ * call inside a string literal will also be rewritten. Document this in the
+ * language reference.
+ */
+function rewriteToRawSetters(code, stateNodes) {
+    let out = code;
+    for (const stateNode of stateNodes) {
+        const sp = getProps(stateNode);
+        // External-state setters use the bare useState form — there is no
+        // `_setXRaw` to rewrite to. Leave call sites alone.
+        if (sp.external === 'true' || sp.external === true)
+            continue;
+        const safe = sp.safe !== 'false' && sp.safe !== false;
+        if (!safe)
+            continue;
+        if (sp.throttle !== undefined || sp.debounce !== undefined)
+            continue;
+        const name = sp.name;
+        if (!name)
+            continue;
+        const setter = `set${capitalize(name)}`;
+        const raw = `_${setter}Raw`;
+        // Negative lookbehind: setter must not be preceded by `.` (member access)
+        // or `\w` (substring of a longer identifier).
+        const pattern = new RegExp(`(?<![\\w.])${setter}\\s*\\(`, 'g');
+        out = out.replace(pattern, `${raw}(`);
+    }
+    return out;
+}
+/**
+ * Refuse to batch handlers that contain async or deferred constructs. The whole
+ * point of batch=true is "collapse N synchronous setter calls into one shared
+ * macrotask." If the handler defers work into a nested timer or promise, those
+ * inner setter calls would land in their own task AFTER the batch's setTimeout
+ * has already flushed, with no __inkSafe wrapper to bridge them — exactly the
+ * missed-repaint failure mode __inkSafe exists to prevent. Better to surface
+ * the misuse at compile time than ship code that silently regresses on a
+ * subset of paths.
+ */
+const BATCH_FORBIDDEN_PATTERNS = [
+    { name: 'setTimeout(', pattern: /\bsetTimeout\s*\(/ },
+    { name: 'setInterval(', pattern: /\bsetInterval\s*\(/ },
+    { name: 'setImmediate(', pattern: /\bsetImmediate\s*\(/ },
+    { name: 'queueMicrotask(', pattern: /\bqueueMicrotask\s*\(/ },
+    { name: 'await', pattern: /\bawait\b/ },
+    { name: '.then(', pattern: /\.then\s*\(/ },
+];
+/**
+ * Append `_${name}Version` to a memo's dep list for every external state name
+ * the memo already references. The user writes `deps="registry"` and the codegen
+ * produces `[registry, _registryVersion]`, so the memo invalidates when the user
+ * calls `bumpRegistry()` after mutating the held object in place. Idempotent —
+ * if the user already listed the version manually, nothing is duplicated.
+ */
+function injectExternalVersionDeps(depsRaw, externalStateNames) {
+    if (externalStateNames.length === 0)
+        return depsRaw;
+    const tokens = depsRaw
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const present = new Set(tokens);
+    for (const name of externalStateNames) {
+        if (!present.has(name))
+            continue;
+        const versionTok = `_${name}Version`;
+        if (!present.has(versionTok)) {
+            tokens.push(versionTok);
+            present.add(versionTok);
+        }
+    }
+    return tokens.join(', ');
+}
+function checkBatchBodyIsSync(code, onNode) {
+    for (const { name, pattern } of BATCH_FORBIDDEN_PATTERNS) {
+        if (pattern.test(code)) {
+            throw new Error(`batch=true handler at on-node '${getProps(onNode).key || getProps(onNode).event || 'unknown'}' contains '${name}'. Batched handlers must be fully synchronous — deferred work would bypass __inkSafe and cause missed repaints. Either remove batch=true or move the deferred work to a separate non-batched on-node.`);
+        }
+    }
+}
+function generateOnHook(onNode, imports, stateNodes) {
     const lines = [];
     const onProps = getProps(onNode);
     const event = (onProps.event || onProps.name);
+    const batch = onProps.batch === 'true' || onProps.batch === true;
     if (event === 'key' || event === 'input') {
         imports.addInk('useInput');
         imports.addReact('useRef');
@@ -532,8 +672,20 @@ function generateOnHook(onNode, imports) {
         }
         if (code) {
             const dedented = dedent(code);
-            for (const line of dedented.split('\n')) {
-                lines.push(`    ${line}`);
+            if (batch) {
+                checkBatchBodyIsSync(dedented, onNode);
+                const body = rewriteToRawSetters(dedented, stateNodes);
+                // Single deferred macrotask: collapse N __inkSafe wrappers into one paint cycle.
+                lines.push(`    setTimeout(() => {`);
+                for (const line of body.split('\n')) {
+                    lines.push(`      ${line}`);
+                }
+                lines.push(`    }, 0);`);
+            }
+            else {
+                for (const line of dedented.split('\n')) {
+                    lines.push(`    ${line}`);
+                }
             }
         }
         lines.push(`  };`);
@@ -607,6 +759,58 @@ function renderInkBox(node, p, indent, imports) {
     lines.push(`${indent}</Box>`);
     return lines;
 }
+function renderInkAlternateScreen(node, p, indent, imports) {
+    imports.addKernRuntime('AlternateScreen');
+    const mouseTracking = p.mouseTracking === 'true' ||
+        p.mouseTracking === true ||
+        p['mouse-tracking'] === 'true' ||
+        p['mouse-tracking'] === true;
+    const attrs = [];
+    if (mouseTracking)
+        attrs.push('mouseTracking');
+    const propsStr = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+    const lines = [];
+    lines.push(`${indent}<AlternateScreen${propsStr}>`);
+    for (const child of node.children || []) {
+        if (child.type === 'on')
+            continue;
+        lines.push(...renderInkNode(child, `${indent}  `, imports));
+    }
+    lines.push(`${indent}</AlternateScreen>`);
+    return lines;
+}
+function renderInkScrollBox(node, p, indent, imports) {
+    imports.addKernRuntime('ScrollBox');
+    const stickyScroll = p.stickyScroll === 'true' ||
+        p.stickyScroll === true ||
+        p['sticky-scroll'] === 'true' ||
+        p['sticky-scroll'] === true;
+    const flexGrow = p.flexGrow ?? p['flex-grow'];
+    const flexShrink = p.flexShrink ?? p['flex-shrink'];
+    const height = p.height;
+    const rowHeight = p.rowHeight ?? p['row-height'];
+    const attrs = [];
+    if (stickyScroll)
+        attrs.push('stickyScroll');
+    if (flexGrow !== undefined)
+        attrs.push(`flexGrow={${unwrapProp(flexGrow)}}`);
+    if (flexShrink !== undefined)
+        attrs.push(`flexShrink={${unwrapProp(flexShrink)}}`);
+    if (height !== undefined)
+        attrs.push(`height={${unwrapProp(height)}}`);
+    if (rowHeight !== undefined)
+        attrs.push(`rowHeight={${unwrapProp(rowHeight)}}`);
+    const propsStr = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+    const lines = [];
+    lines.push(`${indent}<ScrollBox${propsStr}>`);
+    for (const child of node.children || []) {
+        if (child.type === 'on')
+            continue;
+        lines.push(...renderInkNode(child, `${indent}  `, imports));
+    }
+    lines.push(`${indent}</ScrollBox>`);
+    return lines;
+}
 function renderInkTable(node, p, indent, imports) {
     imports.addInk('Box');
     imports.addInk('Text');
@@ -1044,6 +1248,10 @@ function renderInkNode(node, indent, imports) {
             return renderInkSeparator(p, indent, imports);
         case 'box':
             return renderInkBox(node, p, indent, imports);
+        case 'alternate-screen':
+            return renderInkAlternateScreen(node, p, indent, imports);
+        case 'scroll-box':
+            return renderInkScrollBox(node, p, indent, imports);
         case 'table':
             return renderInkTable(node, p, indent, imports);
         case 'scoreboard':
@@ -1209,11 +1417,23 @@ function compileScreenBody(screenNode, imports) {
     }
     if (appExitNodes.length > 0)
         bodyLines.push('');
+    // Names of state nodes declared with external=true. Memos that reference
+    // any of these names auto-receive the corresponding `_${name}Version` token
+    // in their dep array, so the user does not have to remember to list both.
+    const externalStateNames = stateNodes
+        .filter((s) => {
+        const sp = getProps(s);
+        return sp.external === 'true' || sp.external === true;
+    })
+        .map((s) => getProps(s).name)
+        .filter(Boolean);
     // Memo hooks
     for (const memoNode of memoNodes) {
         const mp = getProps(memoNode);
         const mName = mp.name;
-        const mDeps = mp.deps || '';
+        const mDepsRaw = mp.deps || '';
+        // Auto-inject `_${name}Version` for every external state referenced in deps.
+        const mDeps = injectExternalVersionDeps(mDepsRaw, externalStateNames);
         const mDepsArr = mDeps ? `[${mDeps}]` : '[]';
         const handlerChild = (memoNode.children || []).find((c) => c.type === 'handler');
         const code = handlerChild ? getProps(handlerChild).code || '' : '';
@@ -1235,7 +1455,7 @@ function compileScreenBody(screenNode, imports) {
     }
     // on event=key → useInput() hooks
     for (const onNode of allOnNodes) {
-        bodyLines.push(...generateOnHook(onNode, imports));
+        bodyLines.push(...generateOnHook(onNode, imports, stateNodes));
     }
     // Stream effects
     for (const streamNode of streamNodes) {
@@ -1264,7 +1484,9 @@ function compileScreenBody(screenNode, imports) {
             const typeAnnotation = dType ? `<${dType}>` : '';
             let depsStr;
             if (dDeps) {
-                depsStr = `[${dDeps}]`;
+                // Explicit deps — same auto-injection path as memo nodes.
+                const injected = injectExternalVersionDeps(dDeps, externalStateNames);
+                depsStr = `[${injected}]`;
             }
             else {
                 const sNames = stateNodes.map((s) => getProps(s).name).filter(Boolean);
@@ -1276,7 +1498,19 @@ function compileScreenBody(screenNode, imports) {
                     .filter(Boolean);
                 const allNames = [...sNames, ...rNames];
                 const autoDeps = allNames.filter((n) => new RegExp(`\\b${n}\\b`).test(dExpr));
-                depsStr = `[${autoDeps.join(', ')}]`;
+                // After auto-detect, append `_${name}Version` for any external state that
+                // showed up in the expression — otherwise bumpRegistry() never invalidates.
+                const autoDepsWithVersions = [];
+                for (const dep of autoDeps) {
+                    autoDepsWithVersions.push(dep);
+                    if (externalStateNames.includes(dep)) {
+                        const versionTok = `_${dep}Version`;
+                        if (!autoDepsWithVersions.includes(versionTok)) {
+                            autoDepsWithVersions.push(versionTok);
+                        }
+                    }
+                }
+                depsStr = `[${autoDepsWithVersions.join(', ')}]`;
             }
             bodyLines.push(`  const ${dName} = useMemo${typeAnnotation}(() => ${dExpr}, ${depsStr});`);
             bodyLines.push('');
@@ -1457,8 +1691,7 @@ export function transpileInk(root, _config) {
             : '';
         // Full body compilation — same pipeline as primary screen
         const { bodyLines: secBodyLines, stateCtx: secCtx } = compileScreenBody(secScreen, imports);
-        const secExportAttr = secProps.export;
-        const secExportKw = secExportAttr === 'default' ? 'export default' : 'export';
+        const secExportKw = inkScreenExportKeyword(secProps.export);
         const secMemoAttr = secProps.memo;
         const secUseMemo = secMemoAttr === 'true' || secMemoAttr === true || (typeof secMemoAttr === 'string' && secMemoAttr !== 'false');
         const secMemoComp = secUseMemo && typeof secMemoAttr === 'string' && secMemoAttr !== 'true' ? secMemoAttr : null;
@@ -1469,10 +1702,13 @@ export function transpileInk(root, _config) {
                 componentLines.push(...emitInkSafePreamble());
             componentLines.push(...secBodyLines);
             componentLines.push(secMemoExpr ? `}, ${secMemoExpr});` : '});');
-            componentLines.push(`${secExportKw} { ${secName} };`);
+            const secExportStatement = inkScreenExportStatement(secExportKw, secName);
+            if (secExportStatement) {
+                componentLines.push(secExportStatement);
+            }
         }
         else {
-            componentLines.push(`${secExportKw} function ${secName}(${secParam}) {`);
+            componentLines.push(`${secExportKw ? `${secExportKw} ` : ''}function ${secName}(${secParam}) {`);
             if (secCtx.needsInkSafe)
                 componentLines.push(...emitInkSafePreamble());
             componentLines.push(...secBodyLines);
@@ -1481,7 +1717,7 @@ export function transpileInk(root, _config) {
         componentLines.push('');
     }
     // Component (Feature #9: with props) — respect export= and memo= attributes
-    const screenExportAttr = screenProps.export;
+    const screenExportKw = inkScreenExportKeyword(screenProps.export);
     const screenMemoAttr = screenProps.memo;
     const useMemo = screenMemoAttr === 'true' ||
         screenMemoAttr === true ||
@@ -1490,7 +1726,6 @@ export function transpileInk(root, _config) {
     const memoComparatorExpr = memoComparator && isExpr(screenProps.memo) ? screenProps.memo.code : memoComparator;
     if (useMemo) {
         // React.memo wrapper: const Name = React.memo(function Name(props) { ... }, comparator?);
-        const exportKw = screenExportAttr === 'default' ? 'export default' : 'export';
         componentLines.push(`const ${screenName} = React.memo(function ${screenName}(${propsParam}) {`);
         if (stateCtx.needsInkSafe) {
             componentLines.push(...emitInkSafePreamble());
@@ -1502,11 +1737,13 @@ export function transpileInk(root, _config) {
         else {
             componentLines.push('});');
         }
-        componentLines.push(`${exportKw} { ${screenName} };`);
+        const exportStatement = inkScreenExportStatement(screenExportKw, screenName);
+        if (exportStatement) {
+            componentLines.push(exportStatement);
+        }
     }
     else {
-        const exportKw = screenExportAttr === 'default' ? 'export default' : 'export';
-        componentLines.push(`${exportKw} function ${screenName}(${propsParam}) {`);
+        componentLines.push(`${screenExportKw ? `${screenExportKw} ` : ''}function ${screenName}(${propsParam}) {`);
         if (stateCtx.needsInkSafe) {
             componentLines.push(...emitInkSafePreamble());
         }
@@ -1545,20 +1782,22 @@ export function transpileInk(root, _config) {
     // Generate artifacts: entry point + per-screen component files for multi-screen
     const artifacts = [];
     // Entry-point artifact: render(<App />) + waitUntilExit()
-    const entryLines = [];
-    entryLines.push(`#!/usr/bin/env node`);
-    entryLines.push(`import React from 'react';`);
-    entryLines.push(`import { render } from 'ink';`);
-    if (screenExportAttr === 'named') {
-        entryLines.push(`import { ${screenName} } from './${screenName}.js';`);
-    }
-    else {
-        entryLines.push(`import ${screenName} from './${screenName}.js';`);
+    if (screenExportKw) {
+        const entryLines = [];
+        entryLines.push(`#!/usr/bin/env node`);
+        entryLines.push(`import React from 'react';`);
+        entryLines.push(`import { render } from 'ink';`);
+        if (screenExportKw === 'export default') {
+            entryLines.push(`import ${screenName} from './${screenName}.js';`);
+        }
+        else {
+            entryLines.push(`import { ${screenName} } from './${screenName}.js';`);
+        }
+        entryLines.push('');
+        entryLines.push(`const app = render(<${screenName} />);`);
+        entryLines.push(`await app.waitUntilExit();`);
+        artifacts.push({ path: 'index.tsx', content: entryLines.join('\n'), type: 'entry' });
     }
-    entryLines.push('');
-    entryLines.push(`const app = render(<${screenName} />);`);
-    entryLines.push(`await app.waitUntilExit();`);
-    artifacts.push({ path: 'index.tsx', content: entryLines.join('\n'), type: 'entry' });
     // Main component artifact (always emitted so entry-point import resolves)
     artifacts.push({ path: `${screenName}.tsx`, content: code, type: 'component' });
     // Per-screen component artifacts for secondary screens