refactor: address comments.

Author: knightedcodemonkey

docs/next-steps.md

@@ -45,3 +45,19 @@ Focused follow-up work for `@knighted/develop`.
    - Ensure assistant/editor integration remains compatible with this model (edits should target one of the fixed tabs) without expanding to dynamic tab metadata yet.
    - Suggested implementation prompt:
      - "Implement Phase 2 UX/UI tab support in @knighted/develop with a fixed first-pass tab model: Component, Styles, and App only (no arbitrary tab names yet). Add a clear tab UI for switching editor panes, preserve existing editor behavior/content wiring, and keep render/lint/typecheck/diagnostics flows working with the selected tab context where relevant. Keep AI/BYOT feature-flag behavior unchanged, maintain CDN-first runtime constraints, and do not add dependencies. Add targeted Playwright coverage for tab switching, default/active tab behavior, and interactions with existing render/style-mode flows. Validate with npm run lint and targeted Playwright tests."
+
+6. **Document implicit App strict-flow behavior (auto render)**
+   - Add a short behavior matrix in docs that explains when implicit App wrapping is allowed versus when users must define `App` explicitly.
+   - Include concrete Component editor examples for each case so reviewer/user expectations are clear.
+   - Suggested example cases to document:
+     - Allowed implicit wrap (standalone top-level JSX, no imports/declarations), for example:
+       - `(<button type="button">Standalone</button>) as any`
+     - Requires explicit `App` (top-level JSX with declarations/imports), for example:
+       - `const label = 'Hello'`
+       - `const Button = () => <button>{label}</button>`
+       - `(<Button />) as any`
+     - Recommended explicit pattern, for example:
+       - `const Button = () => <button>Hello</button>`
+       - `const App = () => <Button />`
+   - Suggested implementation prompt:
+     - "Document the current implicit App behavior in @knighted/develop for auto-render mode using a compact behavior matrix and concrete component-editor snippets. Clearly distinguish supported implicit wrapping from cases that intentionally require an explicit App (such as top-level JSX mixed with imports/declarations). Keep docs concise, aligned with current runtime behavior, and include at least one positive and one explicit-error example."

playwright/rendering-modes.spec.ts

@@ -288,6 +288,28 @@ test('auto render implicit App includes multiple component declarations', async
   ).toContainText(['bar', 'foo'])
 })
 
+test('auto render does not treat lowercase helpers as implicit components', async ({
+  page,
+}) => {
+  await waitForInitialRender(page)
+
+  await ensurePanelToolsVisible(page, 'component')
+  await page.getByLabel('ShadowRoot').uncheck()
+
+  await setComponentEditorSource(
+    page,
+    [
+      'const helper = () => <button type="button">helper</button>',
+      'function render() { return <div /> }',
+    ].join('\n'),
+  )
+
+  await expect(page.getByRole('status', { name: 'App status' })).toHaveText('Error')
+  await expect(page.locator('#preview-host pre')).toContainText(
+    'Expected a function or const named App.',
+  )
+})
+
 test('auto render wraps standalone JSX with trailing semicolon and comment', async ({
   page,
 }) => {
@@ -307,6 +329,29 @@ test('auto render wraps standalone JSX with trailing semicolon and comment', asy
   ).toContainText('implicit app from jsx expression')
 })
 
+test('auto render requires explicit App for declarations plus top-level JSX expression', async ({
+  page,
+}) => {
+  await waitForInitialRender(page)
+
+  await ensurePanelToolsVisible(page, 'component')
+  await page.getByLabel('ShadowRoot').uncheck()
+
+  await setComponentEditorSource(
+    page,
+    [
+      "const label = 'kept declarations'",
+      'const Button = () => <button type="button">{label}</button>',
+      '(<Button />) as any',
+    ].join('\n'),
+  )
+
+  await expect(page.getByRole('status', { name: 'App status' })).toHaveText('Error')
+  await expect(page.locator('#preview-host pre')).toContainText(
+    'Top-level JSX with declarations or imports requires an explicit App component.',
+  )
+})
+
 test('renders export default arrow component when auto render is disabled', async ({
   page,
 }) => {
@@ -351,10 +396,36 @@ test('renders export default class component in react mode', async ({ page }) =>
 
   await page.getByRole('button', { name: 'Render' }).click()
 
+  await expect(page.getByRole('status', { name: 'App status' })).toHaveText('Rendered')
+  const previewButtons = page
+    .getByRole('region', { name: 'Preview output' })
+    .getByRole('button')
+  await expect(previewButtons.first()).toContainText('default export class')
+})
+
+test('supports export default App without redeclaration', async ({ page }) => {
+  await waitForInitialRender(page)
+
+  await ensurePanelToolsVisible(page, 'component')
+  await page.getByLabel('ShadowRoot').uncheck()
+  await page.getByLabel('Auto render').uncheck()
+
+  await setComponentEditorSource(
+    page,
+    [
+      'function App() {',
+      '  return <button type="button">export default App</button>',
+      '}',
+      'export default App',
+    ].join('\n'),
+  )
+
+  await page.getByRole('button', { name: 'Render' }).click()
+
   await expect(page.getByRole('status', { name: 'App status' })).toHaveText('Rendered')
   await expect(
-    page.getByRole('region', { name: 'Preview output' }).getByRole('button'),
-  ).toContainText('default export class')
+    page.getByRole('region', { name: 'Preview output' }).getByRole('button').first(),
+  ).toContainText('export default App')
 })
 
 test('persists layout and theme across reload', async ({ page }) => {

src/modules/github-pr-drawer.js

@@ -334,7 +334,7 @@ const stripTopLevelAppWrapper = async ({ source, getTopLevelDeclarations }) => {
       return source
     }
 
-    return mergeWhitespaceAroundRemoval(removeRanges({ source, ranges })).trim()
+    return mergeWhitespaceAroundRemoval(removeRanges({ source, ranges }))
   } catch {
     return source
   }

src/modules/jsx-top-level-declarations.js

@@ -1,5 +1,6 @@
 const createEmptyMetadata = () => ({
   declarations: [],
+  importCount: 0,
   hasTopLevelJsxExpression: false,
   topLevelJsxExpressionRange: null,
 })
@@ -28,6 +29,7 @@ export const collectTopLevelTransformMetadata = ({ source, transformJsxSource })
 
   return {
     declarations: Array.isArray(result?.declarations) ? result.declarations : [],
+    importCount: Array.isArray(result?.imports) ? result.imports.length : 0,
     hasTopLevelJsxExpression: result?.hasTopLevelJsxExpression === true,
     topLevelJsxExpressionRange: isSourceRange(result?.topLevelJsxExpressionRange)
       ? result.topLevelJsxExpressionRange

src/modules/render-runtime.js

@@ -404,8 +404,12 @@ export const createRenderRuntimeController = ({
   const hasAppDeclaration = declarations =>
     hasFunctionLikeDeclarationNamed({ declarations, name: 'App' })
 
+  const isComponentLikeName = name => typeof name === 'string' && /^[A-Z]/.test(name)
+
   const getComponentNames = declarations =>
-    getFunctionLikeDeclarationNames({ declarations, excludeNames: ['App'] })
+    getFunctionLikeDeclarationNames({ declarations, excludeNames: ['App'] }).filter(
+      isComponentLikeName,
+    )
 
   const isSourceRange = range =>
     Array.isArray(range) &&
@@ -451,27 +455,41 @@ export const createRenderRuntimeController = ({
       return source
     }
 
-    const { declarations, hasTopLevelJsxExpression, topLevelJsxExpressionRange } =
-      getTopLevelTransformMetadata({ source, transformJsxSource })
+    const {
+      declarations,
+      importCount,
+      hasTopLevelJsxExpression,
+      topLevelJsxExpressionRange,
+    } = getTopLevelTransformMetadata({ source, transformJsxSource })
     if (hasAppDeclaration(declarations)) {
       return source
     }
 
-    const componentNames = getComponentNames(declarations)
-    if (componentNames.length > 0) {
-      const children = componentNames.map(name => `    <${name} />`).join('\n')
-      return `${source}\n\nconst App = () => (\n  <>\n${children}\n  </>\n)`
-    }
-
     if (hasTopLevelJsxExpression) {
       const expressionSource = sourceFromRange({
         source,
         range: topLevelJsxExpressionRange,
       })
 
-      if (expressionSource) {
-        return `const App = () => (${expressionSource})`
+      if (!expressionSource) {
+        throw new Error(
+          'Unable to infer top-level JSX entry for implicit App. Define App explicitly.',
+        )
       }
+
+      if (declarations.length > 0 || importCount > 0) {
+        throw new Error(
+          'Top-level JSX with declarations or imports requires an explicit App component.',
+        )
+      }
+
+      return `const App = () => (${expressionSource})`
+    }
+
+    const componentNames = getComponentNames(declarations)
+    if (componentNames.length > 0) {
+      const children = componentNames.map(name => `    <${name} />`).join('\n')
+      return `${source}\n\nconst App = () => (\n  <>\n${children}\n  </>\n)`
     }
 
     return source
@@ -685,6 +703,16 @@ export const createRenderRuntimeController = ({
       ? withImplicitAppWrapper(source, transformJsxSource)
       : source
     const userCode = executableSource
+      .replace(
+        /^\s*export\s+default\s+([A-Za-z_$][\w$]*)\s*;?\s*$/gm,
+        (match, identifier) => {
+          if (identifier === 'App') {
+            return ''
+          }
+
+          return `const App = ${identifier}`
+        },
+      )
       .replace(/^\s*export\s+default\s+/gm, 'const App = ')
       .replace(/^\s*export\s+(?=function|const|let|var|class)/gm, '')
       .replace(/^\s*export\s*\{[^}]*\}\s*;?\s*$/gm, '')