@barefootjs/jsx 0.31.4 → 0.31.6

package/src/module-exports.ts

@@ -5,6 +5,7 @@
  * This is a compiler-layer concern, not adapter-specific.
  */
 
+import ts from 'typescript'
 import type { ComponentIR, ParamInfo } from './types.ts'
 import { identifierPattern } from './identifier-pattern.ts'
 
@@ -161,6 +162,142 @@ export function findReachableNames(
   return reachable
 }
 
+/**
+ * Which of `candidates` does `bodyText` ASSIGN to?
+ *
+ * Reachability above answers "is this declaration referenced?", which is
+ * the right question for pruning SSR-irrelevant code. It is the wrong
+ * question for a MUTABLE binding: a surviving `let` whose only writer got
+ * pruned is left declared-and-read but never assigned, and TypeScript's
+ * control-flow analysis then narrows it to `never` at every guarded use
+ * (#2598). `closeOverWritersOfMutableBindings` uses this to restore the
+ * missing half of that pair.
+ *
+ * Recognizes the forms that actually write a local binding:
+ *   `x = …`, `x += …` (and every other compound operator), `x++`, `--x`
+ * Destructuring assignment (`[x] = …`, `({ x } = …)`) is deliberately NOT
+ * recognized: it never appears in the ref/handler shapes this exists for,
+ * and a wrong guess here over-retains rather than fails loudly, so leaving
+ * it out keeps the retained set honest. If one shows up, it will present
+ * as this same `never` narrowing and can be added with a fixture.
+ *
+ * Parsed with the TS AST, not matched as text: `identifierPattern` (used
+ * for reference detection above) cannot tell a write from a read, and a
+ * regex for `name\s*=` would match `name == x`, a `name=` inside a string
+ * or JSX attribute, and a property write `obj.name = x` that assigns
+ * nothing of the sort.
+ */
+export function findAssignedNames(
+  bodyText: string,
+  candidates: ReadonlySet<string>,
+): Set<string> {
+  const assigned = new Set<string>()
+  if (candidates.size === 0) return assigned
+
+  const sf = ts.createSourceFile(
+    'bf-assignment-scan.tsx',
+    bodyText,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ false,
+    ts.ScriptKind.TSX,
+  )
+
+  // A bare Identifier on the left of an assignment — `obj.x = …` is a
+  // PropertyAccessExpression and writes through the binding rather than to
+  // it, so it does not count.
+  const record = (target: ts.Node): void => {
+    if (ts.isIdentifier(target) && candidates.has(target.text)) {
+      assigned.add(target.text)
+    }
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isBinaryExpression(node) && isAssignmentOperator(node.operatorToken.kind)) {
+      record(node.left)
+    } else if (
+      (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+      (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken)
+    ) {
+      record(node.operand)
+    }
+    ts.forEachChild(node, visit)
+  }
+
+  ts.forEachChild(sf, visit)
+  return assigned
+}
+
+/**
+ * `findReachableNames`, plus the invariant it cannot express on its own:
+ * **a mutable binding that survives keeps the declarations that write it.**
+ *
+ * Reachability is seeded from the RENDERED JSX, which has already had the
+ * client-only attributes stripped — `ref={setRef}` leaves no `setRef`
+ * behind, and `onClick={handleClick}` is rendered as `onClick={() => {}}`.
+ * That is deliberate: code reachable only from a handler is client-only
+ * and should not be emitted into an SSR template.
+ *
+ * It goes wrong when a `let` outlives its writer. The binding survives
+ * because some OTHER surviving declaration reads it, while its only
+ * assignment lived in a pruned handler — so the emitted template declares
+ * it, reads it, and never assigns it. TypeScript's control-flow analysis
+ * concludes it is permanently `null`, narrows every guarded use to `never`,
+ * and each member access on it fails:
+ *
+ *     let highlightEl: HTMLElement | null = null      // writer was pruned
+ *     const syncScroll = () => {
+ *       if (highlightEl && textareaEl) {
+ *         highlightEl.scrollTop = textareaEl.scrollTop   // TS2339 on `never`
+ *       }
+ *     }
+ *
+ * Pulling the writers back in restores the source's shape for exactly the
+ * bindings that survived — nothing else. The retained writer is dead code
+ * at SSR (it only ever runs from a hydrated event), which is the same
+ * harmless-unused-declaration trade `generateModuleScopeDeclarations`
+ * already makes deliberately.
+ *
+ * Iterates to a fixpoint because a newly retained writer can read further
+ * declarations, and can itself write another mutable binding. Bounded by
+ * the declaration count: each round either adds a name or stops.
+ */
+export function closeOverWritersOfMutableBindings(
+  primaryRefs: string,
+  declarations: { name: string; body: string }[],
+  mutableNames: ReadonlySet<string>,
+): Set<string> {
+  let reachable = findReachableNames(primaryRefs, declarations)
+  if (mutableNames.size === 0) return reachable
+
+  let seedText = primaryRefs
+  for (let round = 0; round <= declarations.length; round++) {
+    const survivingMutables = new Set(
+      [...reachable].filter(name => mutableNames.has(name)),
+    )
+    if (survivingMutables.size === 0) return reachable
+
+    const added = declarations
+      .filter(d => !reachable.has(d.name))
+      .filter(d => findAssignedNames(d.body, survivingMutables).size > 0)
+      .map(d => d.name)
+    if (added.length === 0) return reachable
+
+    // Re-seed by NAME rather than merging sets directly, so each retained
+    // writer's own transitive dependencies come along through the same
+    // traversal instead of a second, divergent one.
+    seedText += '\n' + added.join('\n')
+    reachable = findReachableNames(seedText, declarations)
+  }
+  return reachable
+}
+
+function isAssignmentOperator(kind: ts.SyntaxKind): boolean {
+  return (
+    kind >= ts.SyntaxKind.FirstAssignment &&
+    kind <= ts.SyntaxKind.LastAssignment
+  )
+}
+
 /**
  * Extract parameter names from a function expression string.
  * Handles: arrow functions, single-param arrows, function expressions.

package/src/scope/binding-scope.ts

@@ -201,7 +201,7 @@ export class BindingScope {
    *     qualifies, including a preamble local shadowing a module const.
    *     These call `isBound` / `boundNames()`.
    *   - REACTIVITY / SLOT-ID CLASSIFIERS (`referencesLoopParam`,
-   *     `hasReactiveAttributes`, and the `BindingEnvironment.loopParams`
+   *     `hasReactiveAttributes`, and the `BindingEnvironment.loopValueBoundNames`
    *     feed built from `makeBindingEnv`, all in `jsx-to-ir.ts`) ask
    *     "does this expression read a value that changes per row and so
    *     needs its own patchable slot" — a preamble local already gets

package/src/types.ts

@@ -901,6 +901,28 @@ export interface MapCallbackPreamble {
    * keeps the plain interpolation it always had.
    */
   builderNames: string[]
+  /**
+   * The subset of {@link declaredNames} whose OWN initializer is itself
+   * reactive — reads a signal / memo / reactive prop, directly or
+   * transitively through an earlier preamble declaration (#2596). `undefined`
+   * (never an empty array) when the preamble contributes no such name, or
+   * when it isn't a value-only declaration sequence this analysis covers
+   * (see `preambleFromValueStatements`'s caller — a JSX-building preamble
+   * doesn't compute this and leaves it unset).
+   *
+   * Used to decide whether a loop-body CONDITIONAL whose condition
+   * bare-references a preamble local should carry the IR `reactive` flag
+   * (`markPreambleConditionalReactivity`, jsx-to-ir.ts). Deliberately NOT the
+   * same test `collectPreambleRegions`/`markPreambleAttrSlots` use for
+   * text/attr positions — those mark ANY reference to `declaredNames`
+   * reactive because their region-patch effect re-runs the whole preamble
+   * unconditionally on row update, and ordinary signal auto-tracking inside
+   * that effect picks up genuine dependencies regardless of the IR flag. A
+   * conditional instead swaps whole DOM subtrees via `insert()`, so it stays
+   * unwrapped unless the local it reads is proven to depend on an actual
+   * external signal — a bare `item.title`-derived local needs no such wrap.
+   */
+  reactiveNames?: string[]
 }
 
 /**
@@ -1940,6 +1962,25 @@ export interface IRMetadata {
   isClientComponent: boolean
   typeDefinitions: TypeDefinition[]
   propsType: TypeInfo | null
+  /**
+   * The component function's own generic type parameter list, verbatim
+   * from source (each `node.getText()`, joined and wrapped in `<...>`),
+   * e.g. `<NodeType extends NodeBase = NodeBase, EdgeType extends
+   * EdgeBase = EdgeBase>`. `null` when the component isn't generic.
+   *
+   * A generic function component's props type (and often its body) keeps
+   * referencing these names verbatim in emitted output (e.g. `props:
+   * FlowComponentProps<NodeType, EdgeType>`, `createFlowStore<NodeType,
+   * EdgeType>(props)`) — without the function's own declaration also
+   * carrying the type parameters, those references are unresolved names
+   * in the emitted `.tsx` (TS2304). Emitters that print a `function
+   * <name>(...)` signature for the component must splice this verbatim
+   * between the name and the parameter list. Optional (rather than
+   * required) so the many hand-built `IRMetadata` test fixtures across
+   * the suite don't need updating for a field that is `null` for the
+   * overwhelming majority of (non-generic) components.
+   */
+  typeParameters?: string | null
   propsParams: ParamInfo[]
   /** Name of the props object parameter (e.g., 'props' in `function Component(props: Props)`) */
   propsObjectName: string | null
@@ -2151,9 +2192,62 @@ export interface CompilerError {
   suggestion?: ErrorSuggestion
 }
 
+/**
+ * The kind of escape available from a refusal — the way a user gets their
+ * legitimate, in-subset JSX to compile on an adapter that cannot host it
+ * (#2613).
+ *
+ * Lives here, next to `ErrorSuggestion`, because both halves of the
+ * "loud-or-escapable" contract must speak the SAME enum: the diagnostic
+ * CLAIMS kinds (`ErrorSuggestion.escape`) and a conformance fixture
+ * DEMONSTRATES them (`JSXFixture.escapes`, which re-exports this type —
+ * `@barefootjs/adapter-tests` depends on this package, not the reverse).
+ * `escape-coverage.test.ts` then checks claims are a subset of what the
+ * twins prove, which is only meaningful while the two share one union.
+ */
+export type EscapeKind = 'client-directive' | 'prop-precompute' | 'rewrite'
+
+/**
+ * What an escape costs at SSR. `'none'` — full server render, the result
+ * is present in the server HTML. `'client-render'` — the region is EMPTY
+ * in server HTML until hydration.
+ *
+ * Output-equivalence is explicitly NOT the bar for an escape (#2613): a
+ * `/* @client *\/` region is definitionally not equivalent, and that is a
+ * legitimate trade the user chooses. Making the cost typed and visible is
+ * the honest substitute for pretending it doesn't exist — every renderer
+ * that surfaces an escape surfaces its cost from THIS map, so the trade
+ * can never be quietly dropped on the way to a user.
+ */
+export type EscapeSsrCost = 'none' | 'client-render'
+
+export const ESCAPE_SSR_COST: Record<EscapeKind, EscapeSsrCost> = {
+  // `/* @client */` — compiles and hydrates correctly, renders nothing at SSR.
+  'client-directive': 'client-render',
+  // The refused computation moves to an already-computed prop.
+  'prop-precompute': 'none',
+  // The source is restructured into an equivalent in-subset shape.
+  rewrite: 'none',
+}
+
 export interface ErrorSuggestion {
   message: string
   replacement?: string
+  /**
+   * The escape kinds this diagnostic CLAIMS are available, structured
+   * (#2613 increment 3). Additive and one-way: `message` stays
+   * authoritative for humans — several sites have genuinely good
+   * site-specific prose no enum should flatten — while this field is
+   * authoritative for machines (`bf compat`'s legend, the docs matrix,
+   * claim verification). New and edited refusal sites populate it; older
+   * sites migrate opportunistically, so ABSENT means "not yet declared",
+   * never "no escape exists".
+   *
+   * Order carries the recommendation: list a `ssrCost: 'none'` escape
+   * before a `'client-render'` one, matching the prose rule that a
+   * full-SSR way out is offered first.
+   */
+  escape?: ReadonlyArray<{ kind: EscapeKind }>
 }
 
 /**
@@ -2170,6 +2264,30 @@ export interface ConformancePin {
   severity: 'error' | 'warning'
   /** Tracking issue URL (known-limitation label) for this refusal, when one exists. */
   issue?: string
+  /**
+   * Present when THIS adapter has no verified escape yet for this
+   * refusal — the per-adapter half of #2613's "loud-or-escapable" floor
+   * (`packages/compat/src/__tests__/escape-coverage.test.ts`). `issue` is
+   * the tracking pointer for closing the gap (fall back to
+   * https://github.com/piconic-ai/barefootjs/issues/2613 itself when no
+   * more specific issue exists yet).
+   *
+   * Declared here, next to the refusal it qualifies, so an adapter's own
+   * package is the sole place that states what it knows about its own
+   * refusal — no central cross-adapter ledger to keep in sync (that was
+   * the architectural defect increment 1 shipped with: a `packages/compat`
+   * test hardcoding every adapter's id, which made adapters non-additive).
+   *
+   * Absent means the adapter believes an escape is owed here — either
+   * already satisfied (the refused fixture's `escapes` twin compiles
+   * clean, unpinned, non-divergent, and not CSR-skipped on THIS adapter)
+   * or a pending gap the floor test won't let merge silently.
+   *
+   * Shrink-only, same discipline `KNOWN_HOLES` established: once a
+   * working twin exists here, a lingering `unescapable` becomes a STALE
+   * declaration and the floor test fails loudly on it, naming this pin.
+   */
+  unescapable?: { issue: string }
 }
 /** Keyed by shared-fixture id (`JSXFixture.id`). */
 export type ConformancePins = Record<string, ReadonlyArray<ConformancePin>>