partial-tsx 0.0.4 → 0.0.6

package/README.md

@@ -19,7 +19,10 @@ normalizeGeneratedTsx("function Card() { return <button>OK");
   - Markdown fences removed.
   - Safe partial syntax completed.
   - Missing default export added when a component can be found.
+    Pass `{ synthesizeDefaultExport: false }` to skip this and wait for the author's own `export default`.
+    Which side to pick is a deliberate trade-off — spelled out on `PartialTsxOptions.synthesizeDefaultExport`.
   - Missing imports added for known React hooks such as `useState`.
+- `normalizeGeneratedTsxWithMetadata(code)` returns that same TSX as `source`, plus the `inferredComponent` it synthesized the default export from (absent when the code already declares one). Pass `{ preferredComponent }` to keep that component selected while the source still ends inside an unfinished statement, so a host streaming a prefix can hold an entry it has already displayed. At a top-level boundary the last declared component wins again.
 - `{ mode: "streaming" }` first rolls script back to its last committed syntax boundary. It never closes an unfinished call, initializer, callback, control-flow statement, or JSX `{expression`; unterminated JSX string attributes remain the one value-completion exception.
 - The default `{ mode: "final" }` preserves the existing completion behavior. `partial-react` uses streaming mode only for incremental frames and sends final input to the compiler unchanged.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "partial-tsx",
   "description": "Utilities for completing prefix-growing TSX.",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "repository": {
     "type": "git",

package/src/partial.ts

@@ -2,9 +2,29 @@ const VOID_TAGS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "i
 const BLOCK_FOLLOWERS: Record<string, string> = { "{": "}", "(": ")", "[": "]" };
 const BLOCK_CLOSERS = new Set(Object.values(BLOCK_FOLLOWERS));
 export type PartialTsxMode = "streaming" | "final";
-export type PartialTsxOptions = { mode?: PartialTsxMode };
+export type PartialTsxOptions = {
+  mode?: PartialTsxMode;
+  // Deliberate trade-off, not a bug fix — please keep both sides in mind before flipping the default.
+  //
+  // On (the default): every component declared so far gets a turn as the entry point, so a growing buffer shows
+  // something as early as possible. The payoff is more streaming and more of the intermediate process on screen,
+  // which is what makes a live preview feel alive and is why the debug workbenches want it.
+  //
+  // The cost is that those intermediate frames are not always what a viewer should be seeing yet. A half-written
+  // modal shows up as a stray fragment; an answer renders as a loose piece of its own text. They are closer to
+  // demo material and inspiration than to a product surface, and the synthesized default also tracks whichever
+  // component is currently last, so a helper that precedes the real `export default` paints, then gives way to a
+  // half-written entry point and blanks the pane.
+  //
+  // Off: wait for the author's own `export default`. Less to look at while the code is still growing, but every
+  // frame that does paint is a frame that is meant to be seen. The embed turns it off for that reason; a
+  // live-typing preview leaves it on.
+  synthesizeDefaultExport?: boolean;
+};
+// `preferredComponent` only steers the implicit-entry choice, which `completePartialTsx` does not make.
+export type NormalizeGeneratedTsxOptions = PartialTsxOptions & { preferredComponent?: string };
 type BlockKind = "function" | "control" | "arrow" | "class" | "method" | "block" | "other";
-type CompletionFrame = { type: "block"; closer: string; statement: boolean; open?: number; close?: number; jsxExpression?: boolean; statementStart?: number; kind?: BlockKind } | { type: "jsx"; tag: string; open?: number };
+type CompletionFrame = { type: "block"; closer: string; statement: boolean; open?: number; close?: number; headerEnd?: number; jsxExpression?: boolean; statementStart?: number; kind?: BlockKind } | { type: "jsx"; tag: string; open?: number };
 
 // Single source of truth for the JSX-text fast path in the four lexer loops below: only `<` (child tag) and `{` (child
 // expression) leave text mode, so none of them reads `(`/`[`/quotes/`//` in ordinary text as unfinished JavaScript.
@@ -168,7 +188,8 @@ const isAmbientDeclaration = (code: string, index: number) => /\bdeclare\s+(?:ab
 const findExpressionBindingName = (code: string, index: number) => /\b(?:const|let|var)\s+([A-Z][\w$]*)\s*(?::[^=]+)?=\s*(?:[A-Za-z_$][\w$.]*\s*(?:<[^<>()]*>)?\s*\(\s*)?$/.exec(code.slice(0, index))?.[1] ?? null;
 const isExpressionPosition = (code: string, index: number) => !/(?:^|[;}]|(?<!\$)\{|\n)\s*(?:(?:export\s+)?(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?)$/.test(code.slice(0, index));
 
-const findLastExportableComponent = (code: string) => {
+// `isTrailingOpen` is lazy: only a live preference that the last-declared rule would override pays for the extra scan.
+const findExportableComponent = (code: string, preferredComponent?: string, isTrailingOpen?: () => boolean) => {
   const candidates: Array<{ name: string; index: number }> = [];
   for (const match of code.matchAll(/\bfunction\s+([A-Z][\w$]*)\s*\(/g)) {
     const index = match.index ?? 0;
@@ -186,7 +207,17 @@ const findLastExportableComponent = (code: string) => {
   for (const match of code.matchAll(/\b(?:const|let|var)\s+([A-Z][\w$]*)\s*(?::[^=]+)?=\s*(?:[A-Za-z_$][\w$]*\.)?(?:memo|forwardRef)\s*/g)) {
     if (findWrappedComponentCallOpen(code, (match.index ?? 0) + match[0].length) !== -1) candidates.push({ name: match[1], index: match.index ?? 0 });
   }
-  return candidates.toSorted((left, right) => left.index - right.index).at(-1)?.name ?? null;
+  const last = candidates.toSorted((left, right) => left.index - right.index).at(-1)?.name;
+  if (!last || last === preferredComponent || !candidates.some((candidate) => candidate.name === preferredComponent)) return last;
+  return isTrailingOpen?.() ? preferredComponent : last;
+};
+// A preference only bridges the frames where the stream stops inside a statement (e.g. a helper's unclosed body completed to an
+// empty `function WhyOnlyA(){}`). Once the source reaches a top-level boundary, last-declared wins again, so a leading helper
+// that rendered first cannot keep the entry from the component declared after it.
+// An EOF comment is reported as an unclosed literal too, but it cannot extend the statement before it.
+const isInsideStatement = (code: string) => {
+  const { stack, unclosedLiteralStart, incompleteJsxTagStart } = scanStreamingSource(code);
+  return stack.length > 0 || incompleteJsxTagStart !== null || (unclosedLiteralStart !== null && !/^\/[/*]/.test(code.slice(unclosedLiteralStart)));
 };
 // `export default` is also valid mid-line after a `;` or block-closing `}` (`;export default …`, `if(a){} export default …`); match those
 // so the scan does not miss an existing default and append a second one (`Duplicate export of 'default'`).
@@ -212,7 +243,7 @@ const maskAmbientBlocks = (scanned: string) => {
 // Reuse the normalizer's lexical scan: component declarations inside comments or strings are not preview entry points.
 export function hasReactComponent(code: string) {
   const scanned = maskAmbientBlocks(maskIgnoredTextForExportScan(code));
-  if (findLastExportableComponent(scanned)) return true;
+  if (findExportableComponent(scanned)) return true;
   for (const match of scanned.matchAll(/(?:^|[\n;}])\s*export\s+default\s+(?:async\s+)?/g)) {
     const start = match.index + match[0].length;
     const expression = scanned.slice(start);
@@ -321,10 +352,10 @@ const isLikelyJsxTagStart = (code: string, index: number) => {
   return previousChar !== ">";
 };
 
-const isLikelyStatementBlock = (code: string, index: number, stack: CompletionFrame[]) => {
+const isLikelyStatementBlock = (code: string, index: number, headerEnd: number, stack: CompletionFrame[]) => {
   // A JSX child expression stays an expression even when the preceding prose looks like a JavaScript block header.
   if (code[index] !== "{" || isInsideJsxText(stack)) return false;
-  const before = code.slice(0, index).trimEnd();
+  const before = code.slice(0, headerEnd).trimEnd();
   return /\bfunction(?:\s+[\w$]+)?\s*\([^)]*\)$/.test(before) || /\b(?:if|for|while|switch|with)\s*\([^)]*\)$/.test(before) || /\bcatch(?:\s*\([^)]*\))?$/.test(before) || /(?:^|[^\w$])(?:else|try|finally|do)$/.test(before) || before.endsWith("=>");
 };
 
@@ -1240,10 +1271,13 @@ const scanStreamingSource = (code: string): StreamingScan => {
       statementRegexBoundary = false;
       const inheritedStart = currentStatementStart();
       const jsxExpression = char === "{" && insideJsxText;
-      const kind = jsxExpression ? undefined : getBlockKind(code, index, inheritedStart);
+      // Both classification and later JSX-shell checks must stop before trailing comments. Reuse lexical provenance
+      // instead of rescanning the prefix or stripping comment-like text inside literals (#1814).
+      const headerEnd = lastSignificantEnd;
+      const kind = jsxExpression ? undefined : getBlockKind(code, headerEnd, inheritedStart);
       const statement = !jsxExpression && kind !== "other";
-      const statementStart = statement ? findKeywordStart(code, index, inheritedStart, kind ?? "other") : inheritedStart;
-      stack.push({ type: "block", closer: BLOCK_FOLLOWERS[char], statement, open: index, jsxExpression, statementStart, kind });
+      const statementStart = statement ? findKeywordStart(code, headerEnd, inheritedStart, kind ?? "other") : inheritedStart;
+      stack.push({ type: "block", closer: BLOCK_FOLLOWERS[char], statement, open: index, headerEnd, jsxExpression, statementStart, kind });
       if (statement && char === "{") scopes.push({ statementStart: index + 1 });
       lastSignificantEnd = index + 1;
       index += 1;
@@ -1286,7 +1320,7 @@ const scanStreamingSource = (code: string): StreamingScan => {
   return { stack, closedBlocks, scopes, regexLiteralStarts, lastSignificantEnd, unclosedLiteralStart, unclosedLiteralStatementStart, incompleteJsxTagStart };
 };
 
-const getFrameHeader = (code: string, frame: Extract<CompletionFrame, { type: "block" }>) => code.slice(frame.statementStart ?? 0, frame.open ?? 0).trim();
+const getFrameHeader = (code: string, frame: Extract<CompletionFrame, { type: "block" }>) => code.slice(frame.statementStart ?? 0, frame.headerEnd ?? frame.open ?? 0).trim();
 const isComponentFunctionFrame = (code: string, frame: Extract<CompletionFrame, { type: "block" }>) => /^[A-Z]/.test(FUNCTION_HEADER.exec(getFrameHeader(code, frame))?.[1] ?? "");
 const isFunctionDeclarationFrame = (code: string, frame: Extract<CompletionFrame, { type: "block" }>) => FUNCTION_HEADER.test(getFrameHeader(code, frame));
 const isComponentClassFrame = (code: string, frame: Extract<CompletionFrame, { type: "block" }>) => /^[A-Z]/.test(CLASS_HEADER.exec(getFrameHeader(code, frame))?.[1] ?? "");
@@ -1642,6 +1676,7 @@ export function completePartialTsx(code: string, options: PartialTsxOptions = {}
   };
   const stack: CompletionFrame[] = [];
   let index = 0;
+  let lastSignificantEnd = 0;
   const push = (value: string) => {
     output += value;
   };
@@ -1650,6 +1685,7 @@ export function completePartialTsx(code: string, options: PartialTsxOptions = {}
     // Keep completion and committed-prefix scanning in the same lexical mode; never append ')' or ']' to plain text.
     if (isInsideJsxText(stack) && !isJsxTextBoundary(char)) {
       push(char);
+      if (!/\s/.test(char)) lastSignificantEnd = index + 1;
       index += 1;
       continue;
     }
@@ -1674,16 +1710,22 @@ export function completePartialTsx(code: string, options: PartialTsxOptions = {}
       index = closeIndex + 2;
       continue;
     }
+    // Match scanStreamingSource's header boundary without losing comments from the completed output.
+    const headerEnd = lastSignificantEnd;
+    if (!/\s/.test(char)) lastSignificantEnd = index + 1;
     if (regexLiteralStarts?.has(index) || isLikelyRegexLiteralStart(code, index)) {
       index = consumeRegexLiteral(code, index, push);
+      lastSignificantEnd = index;
       continue;
     }
     if (char === '"' || char === "'") {
       index = consumeStringLiteral(code, index, push);
+      lastSignificantEnd = index;
       continue;
     }
     if (char === "`") {
       index = consumeTemplateLiteral(code, index, push);
+      lastSignificantEnd = index;
       continue;
     }
     if (char === "<" && isInsideJsxText(stack) && !shouldStartJsxTag(code, index, stack) && index < code.length - 1) {
@@ -1712,11 +1754,12 @@ export function completePartialTsx(code: string, options: PartialTsxOptions = {}
       const tagName = match?.[1] ?? (tag === "<>" || tag === "</>" ? "" : null);
       if (!(tagName && VOID_TAGS.has(tagName) && tag.startsWith("</"))) push(tagName && VOID_TAGS.has(tagName) && !tag.endsWith("/>") ? tag.replace(/\s*\/?\s*>$/, " />") : tag);
       index = closeIndex + 1;
+      lastSignificantEnd = index;
       updateJsxStackForTag(stack, tag);
       continue;
     }
     if (char in BLOCK_FOLLOWERS) {
-      stack.push({ type: "block", closer: BLOCK_FOLLOWERS[char], statement: isLikelyStatementBlock(code, index, stack), open: output.length, jsxExpression: char === "{" && isInsideJsxText(stack) });
+      stack.push({ type: "block", closer: BLOCK_FOLLOWERS[char], statement: isLikelyStatementBlock(code, index, headerEnd, stack), open: output.length, jsxExpression: char === "{" && isInsideJsxText(stack) });
       push(char);
       index += 1;
       continue;
@@ -1744,17 +1787,21 @@ export function completePartialTsx(code: string, options: PartialTsxOptions = {}
   return finish(completedExpression, `${isExpressionEnd(completedExpression) ? ";" : ""}${closingFrames.slice(statementIndex).map(closeFrame).join("")}`);
 }
 
-export function normalizeGeneratedTsx(code: string, options: PartialTsxOptions = {}) {
-  let next = completePartialTsx(stripMarkdownFence(code), options).trim();
+export function normalizeGeneratedTsx(code: string, options: NormalizeGeneratedTsxOptions = {}) {
+  return normalizeGeneratedTsxWithMetadata(code, options).source;
+}
+
+/** Hosts may retain an already displayed implicit entry without treating a synthesized export as an explicit one. */
+export function normalizeGeneratedTsxWithMetadata(code: string, options: NormalizeGeneratedTsxOptions = {}): { source: string; inferredComponent?: string } {
+  const raw = stripMarkdownFence(code);
+  let next = completePartialTsx(raw, options).trim();
   let exportScanCode = maskIgnoredTextForExportScan(next);
   // The ordinary lexer recognizes every regex position except a new statement after a closed block. The first mask removes
   // false candidates from JSX/templates/comments, so only the ambiguous `} /* trivia */ /regex/` shape pays for provenance.
   if (/}\s*\/(?![/*])/.test(exportScanCode)) exportScanCode = maskIgnoredTextForExportScan(next, scanStreamingSource(next).regexLiteralStarts);
   exportScanCode = maskAmbientBlocks(exportScanCode);
-  if (!hasDefaultExportDeclaration(exportScanCode)) {
-    const componentName = findLastExportableComponent(exportScanCode);
-    if (componentName) next += `\nexport default ${componentName};`;
-  }
+  const inferredComponent = options.synthesizeDefaultExport !== false && !hasDefaultExportDeclaration(exportScanCode) ? findExportableComponent(exportScanCode, options.preferredComponent, () => isInsideStatement(raw)) : undefined;
+  if (inferredComponent) next += `\nexport default ${inferredComponent};`;
   next = injectMissingReactHookImports(next, exportScanCode);
-  return next;
+  return { source: next, inferredComponent };
 }