fix: code review hardening — blockjs precedence, exports types, readme/link.sh cleanups (#933)

addresses review findings on #942:

- staticprops: move blockjs after the ...serializeOptions spread and use
  serializeOptions.blockJS ?? false so a consumer's blockJS: undefined
  (from a destructure-respread) no longer silently re-enables
  next-mdx-remote@6's destructive blockJS: true default. explicit
  blockJS: true from a consumer is still honoured.
- package.json exports: convert the five .js-suffix wildcard entries
  (./lib/*.js, ./nextauth/*.js, ./google/*.js, ./terra/*.js, ./auth/*.js)
  from bare-string targets to conditional { types, default } form so
  node16 / nodenext consumers using explicit .js imports resolve the
  matching .d.ts instead of falling through to filesystem heuristics.
- package.json: add top-level "types": "lib/index.d.ts" next to "main"
  so legacy moduleResolution "node" consumers (and any tool that
  ignores exports) find the bare-package type entry.
- readme: add import { JSX } from "react" to the _app.tsx and
  _document.tsx snippets (react 19 removed the global JSX namespace)
  and export default MyApp; to the _app.tsx snippet (consumer
  copy-paste needs the default export for the next pages router to
  pick it up).
- readme: flag the --webpack workaround as temporary, point at
  vercel/next.js#82607 for subscription, and ask consumers to
  re-review on each next major.
- scripts/link.sh: rm -rf lib before tsc so renames and barrel
  deletions don't leave stale artefacts that get packed into the
  tarball — would otherwise silently mask breaking-change import
  paths during local migration testing. updated header comment to
  reflect actually-packed paths (lib + types, not src).
- readme: blank lines around three pre-existing fenced code blocks
  in the developing-alongside-a-consuming-app section, satisfies
  md031.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: frano-m

README.md

@@ -51,7 +51,7 @@ Until the upstream fix lands ([vercel/next.js#82607](https://github.com/vercel/n
 }
 ```
 
-Webpack is still fully supported in Next 16 — Turbopack was promoted to default, not "webpack removed." The deprecation timeline for the webpack fallback hasn't been published.
+Webpack is still fully supported in Next 16 — Turbopack was promoted to default, not "webpack removed." The deprecation timeline for the webpack fallback hasn't been published, but the `--webpack` flag is a temporary workaround and is expected to be removed in a future major. **Subscribe to [vercel/next.js#82607](https://github.com/vercel/next.js/issues/82607) for status**, and review this pin whenever Next.js publishes a webpack removal notice or the upstream Turbopack + Pages Router + MUI bug is resolved.
 
 This is a Next.js / Turbopack bug, not a findable-ui one. Re-enable Turbopack when [vercel/next.js#82607](https://github.com/vercel/next.js/issues/82607) is closed.
 
@@ -63,6 +63,7 @@ Wrap the app in `AppCacheProvider`:
 import { EmotionCache } from "@emotion/react";
 import { AppCacheProvider } from "@mui/material-nextjs/v16-pagesRouter";
 import type { AppProps } from "next/app";
+import { JSX } from "react";
 
 type MyAppProps = AppProps & {
   emotionCache?: EmotionCache;
@@ -77,6 +78,8 @@ function MyApp(props: MyAppProps): JSX.Element {
     </AppCacheProvider>
   );
 }
+
+export default MyApp;
 ```
 
 ### `_document.tsx`
@@ -96,6 +99,7 @@ import Document, {
   Main,
   NextScript,
 } from "next/document";
+import { JSX } from "react";
 
 class MyDocument extends Document<DocumentHeadTagsProps> {
   render(): JSX.Element {
@@ -145,21 +149,25 @@ into a consuming project (e.g. ncpi-dataset-catalog, data-browser):
 2. Set `node` version to `22.13.0`.
 3. Run `npm install` in both repositories.
 4. From the consuming project directory:
+
    ```bash
    ../findable-ui/scripts/link.sh
    ```
+
    This compiles TypeScript, packs the output, installs it into
    `node_modules`, clears the Next.js cache, and starts the dev server.
 
 5. To iterate: Ctrl+C the dev server, make changes in findable-ui, and
    hit up-arrow to re-run the script.
 
 6. To restore the published version:
+
    ```bash
    ../findable-ui/scripts/unlink.sh
    ```
 
 Consuming projects can optionally add thin wrappers in their `package.json` scripts:
+
 ```json
 {
   "scripts": {

package.json

@@ -21,6 +21,7 @@
   },
   "homepage": "https://github.com/DataBiosphere/findable-ui/tree/main/#readme",
   "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "sideEffects": false,
   "files": [
     "lib",
@@ -31,27 +32,42 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./lib/*.js": "./lib/*.js",
+    "./lib/*.js": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    },
     "./lib/*": {
       "types": "./lib/*.d.ts",
       "default": "./lib/*.js"
     },
-    "./nextauth/*.js": "./lib/nextauth/*.js",
+    "./nextauth/*.js": {
+      "types": "./lib/nextauth/*.d.ts",
+      "default": "./lib/nextauth/*.js"
+    },
     "./nextauth/*": {
       "types": "./lib/nextauth/*.d.ts",
       "default": "./lib/nextauth/*.js"
     },
-    "./google/*.js": "./lib/google/*.js",
+    "./google/*.js": {
+      "types": "./lib/google/*.d.ts",
+      "default": "./lib/google/*.js"
+    },
     "./google/*": {
       "types": "./lib/google/*.d.ts",
       "default": "./lib/google/*.js"
     },
-    "./terra/*.js": "./lib/terra/*.js",
+    "./terra/*.js": {
+      "types": "./lib/terra/*.d.ts",
+      "default": "./lib/terra/*.js"
+    },
     "./terra/*": {
       "types": "./lib/terra/*.d.ts",
       "default": "./lib/terra/*.js"
     },
-    "./auth/*.js": "./lib/auth/*.js",
+    "./auth/*.js": {
+      "types": "./lib/auth/*.d.ts",
+      "default": "./lib/auth/*.js"
+    },
     "./auth/*": {
       "types": "./lib/auth/*.d.ts",
       "default": "./lib/auth/*.js"

scripts/link.sh

@@ -12,8 +12,10 @@
 #   3. The script builds, installs, and restarts the dev server for you
 #
 # How it works:
+#   - Cleans the previous build output (lib/) so renames and deletions don't
+#     leave stale artefacts in the packed tarball
 #   - Compiles findable-ui's TypeScript source into lib/
-#   - Packs lib/, src/, and types/ into a tarball (see "files" in package.json)
+#   - Packs lib/ and types/ into a tarball (see "files" in package.json)
 #   - Installs the tarball into the consumer's node_modules WITHOUT modifying
 #     the consumer's package.json (--no-save), so "npm install" can restore
 #     the registry version at any time (see unlink.sh)
@@ -31,6 +33,12 @@ CONSUMER_DIR="$PWD"
 echo "Building findable-ui from $FINDABLE_DIR..."
 cd "$FINDABLE_DIR"
 
+# Wipe the previous build output. tsc doesn't prune deleted/renamed files, so
+# stale .js/.d.ts artefacts (e.g. removed barrels or pre-rename filenames)
+# would otherwise persist in lib/ and get packed into the tarball — silently
+# masking breaking-change import paths during local migration testing.
+rm -rf lib
+
 # Compile TypeScript to lib/. Called directly to avoid triggering npm lifecycle
 # scripts (e.g. "prepare" would run husky install, which is unnecessary here).
 ./node_modules/.bin/tsc

src/utils/mdx/staticGeneration/staticProps.ts

@@ -36,8 +36,12 @@ export async function buildStaticProps<F extends object, P extends object>(
   // Serialize the MDX content.
   const outline: OutlineItem[] = [];
   const mdxSource = await serialize(content, {
-    blockJS: false,
     ...serializeOptions,
+    // After the spread so a consumer's `blockJS: undefined` (from a
+    // destructure-respread) doesn't silently re-enable next-mdx-remote@6's
+    // destructive `blockJS: true` default. Consumers can still opt in
+    // explicitly by passing `blockJS: true`.
+    blockJS: serializeOptions.blockJS ?? false,
     mdxOptions: {
       development: false,
       rehypePlugins: [rehypeSlug],