📘 docs(nav): Fixing TypeDoc warnings and linking issues

.husky/pre-push

@@ -7,6 +7,10 @@ cd "$REPO_ROOT"
 
 REMOTE_NAME=${1:-origin}
 
+package_tarballs_exist() {
+  find pkgs -maxdepth 1 -name "contentful-*.tgz" -print -quit 2>/dev/null | grep -q .
+}
+
 # Collect changed files for each pushed ref from pre-push hook input
 # Input rows: <local ref> <local sha> <remote ref> <remote sha>
 changed_files=""
@@ -70,6 +74,39 @@ if [ ${#changed_workspaces[@]} -eq 0 ] && [ ${#changed_implementations[@]} -eq 0
   exit 0
 fi
 
+if [ ${#changed_implementations[@]} -gt 0 ]; then
+  package_tarballs_need_refresh=false
+
+  if ! package_tarballs_exist; then
+    package_tarballs_need_refresh=true
+  else
+    for workspace in "${changed_workspaces[@]}"; do
+      case "$workspace" in
+        packages/* | lib/build-tools)
+          package_tarballs_need_refresh=true
+          break
+          ;;
+      esac
+    done
+  fi
+
+  if [ "$package_tarballs_need_refresh" = true ]; then
+    echo "Building local package tarballs before installing changed implementations..."
+    pnpm run build:pkgs
+  fi
+
+  echo "Installing changed implementations before checks:"
+  for implementation in "${changed_implementations[@]}"; do
+    echo "  - implementations/$implementation"
+  done
+
+  for implementation in "${changed_implementations[@]}"; do
+    pnpm run implementation:run -- "$implementation" implementation:install
+  done
+
+  echo "✔ Implementation install complete."
+fi
+
 if [ ${#changed_workspaces[@]} -gt 0 ]; then
   echo "Type-checking and unit testing changed workspaces:"
   for workspace in "${changed_workspaces[@]}"; do

README.md

@@ -10,7 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](./CONTRIBUTING.md)
 
 </div>
@@ -52,7 +53,7 @@ enables developers and content creators to ship their products faster.
 ## Choosing a Package
 
 If you are deciding which SDK or library belongs in your application, start with
-[Choosing the Right SDK](./documentation/choosing-the-right-sdk.md).
+[Choosing the Right SDK](./documentation/guides/choosing-the-right-sdk.md).
 
 For additional narrative documentation, see the [Guides](./documentation/README.md) section.
 

implementations/node-sdk+web-sdk/README.md

@@ -10,7 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>

implementations/node-sdk/README.md

@@ -10,7 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>

implementations/react-native-sdk/README.md

@@ -10,7 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>

implementations/react-web-sdk/README.md

@@ -315,7 +315,9 @@ receive state via `useOutletContext`.
 
 ## Related
 
-- [web-sdk_react](../web-sdk_react/) — adapter-based reference using `@contentful/optimization-web`
-- [web-sdk](../web-sdk/) — vanilla JavaScript reference
-- [@contentful/optimization-react-web](../../packages/web/frameworks/react-web-sdk/) — React Web SDK
-- [@contentful/optimization-web](../../packages/web/web-sdk/) — Web SDK
+- [web-sdk_react](../web-sdk_react/README.md) — adapter-based reference using
+  `@contentful/optimization-web`
+- [web-sdk](../web-sdk/README.md) — vanilla JavaScript reference
+- [@contentful/optimization-react-web](../../packages/web/frameworks/react-web-sdk/README.md) —
+  React Web SDK
+- [@contentful/optimization-web](../../packages/web/web-sdk/README.md) — Web SDK

implementations/web-sdk/README.md

@@ -10,7 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>

implementations/web-sdk_react/README.md

@@ -10,7 +10,8 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>
@@ -194,6 +195,8 @@ function TrackedComponent() {
 
 ## Related
 
-- [React Native Implementation](../react-native-sdk/) - Reference implementation for React Native
-- [Web Vanilla Implementation](../web-sdk/) - Reference implementation for vanilla JavaScript
+- [React Native Implementation](../react-native-sdk/README.md) - Reference implementation for React
+  Native
+- [Web Vanilla Implementation](../web-sdk/README.md) - Reference implementation for vanilla
+  JavaScript
 - [@contentful/optimization-web](../../packages/web/web-sdk/README.md) - Web SDK package

package.json

@@ -61,7 +61,7 @@
   "engines": {
     "node": ">=20.19.0"
   },
-  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
+  "packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8",
   "devDependencies": {
     "@rstest/core": "catalog:",
     "@eslint/js": "^10.0.1",

packages/node/node-sdk/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>
@@ -93,7 +93,7 @@ The Node SDK is stateless, but that does not mean all request work is cacheable.
 
 For a step-by-step Express-style walkthrough that covers request context, profile persistence,
 Contentful entry resolution, and hybrid Node + browser setups, see
-[Integrating the Optimization Node SDK in a Node App](../../../documentation/integrating-the-node-sdk-in-a-node-app.md).
+[Integrating the Optimization Node SDK in a Node App](../../../documentation/guides/integrating-the-node-sdk-in-a-node-app.md).
 
 ## Development Harness
 

packages/node/node-sdk/src/ContentfulOptimization.ts

@@ -1,10 +1,8 @@
-import { CoreStateless } from '@contentful/optimization-core'
+import { CoreStateless, type CoreStatelessConfig } from '@contentful/optimization-core'
 import type { App } from '@contentful/optimization-core/api-schemas'
 import { merge } from 'es-toolkit'
 import { OPTIMIZATION_NODE_SDK_NAME, OPTIMIZATION_NODE_SDK_VERSION } from './constants'
 
-type CoreStatelessConfig = ConstructorParameters<typeof CoreStateless>[0]
-
 /**
  * Configuration for the Node-specific ContentfulOptimization SDK.
  *

packages/react-native-sdk/README.md

@@ -8,7 +8,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
 
 </div>

packages/universal/api-client/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>

packages/universal/api-schemas/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>

packages/universal/core-sdk/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>

packages/universal/core-sdk/src/CoreStateless.ts

@@ -57,13 +57,40 @@ export interface CoreStatelessConfig extends CoreConfig {
   eventBuilder?: Omit<EventBuilderConfig, 'getLocale' | 'getPageProperties' | 'getUserAgent'>
 }
 
-type StatelessExperiencePayload<TPayload> = TPayload & { profile?: PartialProfile }
-type StatelessInsightsPayload<TPayload> = TPayload & { profile: PartialProfile }
-type StatelessStickyTrackViewPayload = ViewBuilderArgs & {
+/**
+ * Payload accepted by stateless Experience methods.
+ *
+ * @typeParam TPayload - Event-builder arguments for the specific method.
+ *
+ * @public
+ */
+export type StatelessExperiencePayload<TPayload> = TPayload & { profile?: PartialProfile }
+
+/**
+ * Payload accepted by stateless Insights methods.
+ *
+ * @typeParam TPayload - Event-builder arguments for the specific method.
+ *
+ * @public
+ */
+export type StatelessInsightsPayload<TPayload> = TPayload & { profile: PartialProfile }
+
+/**
+ * Sticky stateless view-tracking payload.
+ *
+ * @public
+ */
+export type StatelessStickyTrackViewPayload = ViewBuilderArgs & {
   profile?: PartialProfile
   sticky: true
 }
-type StatelessNonStickyTrackViewPayload = Omit<ViewBuilderArgs, 'sticky'> & {
+
+/**
+ * Non-sticky stateless view-tracking payload.
+ *
+ * @public
+ */
+export type StatelessNonStickyTrackViewPayload = Omit<ViewBuilderArgs, 'sticky'> & {
   profile: PartialProfile
   sticky?: false | undefined
 }
@@ -126,7 +153,7 @@ const createStatelessInsightsApiConfig = (
  * Experience and Insights API calls. Cache Contentful delivery data in the
  * host application, not the results of those calls.
  */
-class CoreStateless extends CoreBase<CoreStatelessConfig> {
+class CoreStateless extends CoreBase {
   constructor(config: CoreStatelessConfig) {
     super(config, {
       experience: createStatelessExperienceApiConfig(config.api),

packages/universal/core-sdk/src/index.ts

@@ -33,6 +33,8 @@ export type {
   QueueFlushPolicy,
   QueueFlushRecoveredContext,
 } from './lib/queue'
+export type { ExperienceQueue } from './queues/ExperienceQueue'
+export type { InsightsQueue } from './queues/InsightsQueue'
 export * from './resolvers'
 export * from './symbols'
 

packages/web/frameworks/react-web-sdk/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../../CONTRIBUTING.md)
 
 </div>

packages/web/preview-panel/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>

packages/web/web-sdk/README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
 [Reference](https://contentful.github.io/optimization) · [Contributing](../../../CONTRIBUTING.md)
 
 </div>

typedoc.json

@@ -13,7 +13,21 @@
     "packages/react-native-sdk",
     "packages/universal/*"
   ],
-  "projectDocuments": ["documentation/README.md", "CONTRIBUTING.md"],
+  "projectDocuments": [
+    "documentation/README.md",
+    "CONTRIBUTING.md",
+    "packages/node/node-sdk/README.md",
+    "packages/react-native-sdk/README.md",
+    "packages/universal/api-client/README.md",
+    "packages/universal/api-schemas/README.md",
+    "packages/universal/core-sdk/README.md",
+    "packages/universal/core-sdk/src/preview-support/README.md",
+    "packages/web/frameworks/react-web-sdk/README.md",
+    "packages/web/preview-panel/README.md",
+    "packages/web/web-sdk/README.md",
+    "implementations/*/README.md",
+    "lib/mocks/README.md"
+  ],
   "externalSymbolLinkMappings": {
     "@types/node": {
       "__global.AbortController": "#",