partial-tsx 0.0.5 → 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.5",
+  "version": "0.0.6",
   "type": "module",
   "repository": {
     "type": "git",

package/src/partial.ts

@@ -2,7 +2,27 @@ 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; headerEnd?: number; jsxExpression?: boolean; statementStart?: number; kind?: BlockKind } | { type: "jsx"; tag: string; open?: number };
 
@@ -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);
@@ -1756,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 };
 }