fix(docs): pull bb.js runtime deps via portal in examples

docs/examples/ts/bootstrap.sh

@@ -147,6 +147,7 @@ validate_project() {
 
         local aztec_deps=("${AZTEC_DEPS[@]}")
         local explicit_link_deps=("${EXPLICIT_LINK_DEPS[@]}")
+        local portal_deps=("${PORTAL_DEPS[@]}")
         local npm_deps=("${NPM_DEPS[@]}")
 
         if [ "$PARSED_DEPS_FOUND" = true ]; then
@@ -162,6 +163,12 @@ validate_project() {
                 yarn add "${explicit_link_deps[@]}"
             fi
 
+            # Install portal dependencies (like link:, but also installs the package's own deps)
+            if [ ${#portal_deps[@]} -gt 0 ]; then
+                echo_stderr "Adding portal deps: ${portal_deps[*]}"
+                yarn add "${portal_deps[@]}"
+            fi
+
             # Install external npm dependencies
             if [ ${#npm_deps[@]} -gt 0 ]; then
                 echo_stderr "Adding npm deps: ${npm_deps[*]}"

docs/examples/ts/lib.sh

@@ -5,18 +5,27 @@
 # parse_dependencies <config_file> <repo_root>
 #
 # Reads a config.yaml via yq and classifies each dependency entry into one of
-# three global arrays:
+# these global arrays:
 #   AZTEC_DEPS          — @aztec/* packages resolved to pkg@link:<repo_root>/yarn-project/<name>
 #   EXPLICIT_LINK_DEPS  — link: packages resolved to pkg@link:<repo_root>/<path>
+#   PORTAL_DEPS         — portal: packages resolved to pkg@portal:<repo_root>/<path>
 #   NPM_DEPS            — npm: packages (bare names, e.g. viem)
 #
+# link: vs portal:: link: symlinks the package but does NOT install its own dependencies (the
+# consumer must supply them), whereas portal: also installs the package's declared dependencies at
+# the versions it pins. Use portal: for standalone packages whose runtime deps the example needs
+# (e.g. @aztec/bb.js, which needs pako/msgpackr/...) so the package's own package.json is the single
+# source of truth — rather than hand-mirroring its dependency list here (which drifts and, when left
+# unversioned, floats to breaking majors).
+#
 # Also sets PARSED_DEPS_FOUND to "true" if any dependency was found, "false" otherwise.
 parse_dependencies() {
     local config_file=$1
     local repo_root=$2
 
     AZTEC_DEPS=()
     EXPLICIT_LINK_DEPS=()
+    PORTAL_DEPS=()
     NPM_DEPS=()
     PARSED_DEPS_FOUND=false
 
@@ -42,12 +51,19 @@ parse_dependencies() {
             local link_pkg_name="${link_spec%%:*}"
             local link_path="${link_spec#*:}"
             EXPLICIT_LINK_DEPS+=("${link_pkg_name}@link:${repo_root}/${link_path}")
+        elif [[ "$pkg" =~ ^portal: ]]; then
+            # Portal (installs the package's own deps): portal:@aztec/bb.js:barretenberg/ts/bb.js
+            #   -> @aztec/bb.js@portal:$repo_root/barretenberg/ts/bb.js
+            local portal_spec="${pkg#portal:}"
+            local portal_pkg_name="${portal_spec%%:*}"
+            local portal_path="${portal_spec#*:}"
+            PORTAL_DEPS+=("${portal_pkg_name}@portal:${repo_root}/${portal_path}")
         elif [[ "$pkg" =~ ^@ ]]; then
             # @aztec/* package - auto-link from yarn-project/
             local pkg_name="${pkg#@aztec/}"
             AZTEC_DEPS+=("${pkg}@link:${repo_root}/yarn-project/${pkg_name}")
         else
-            echo "Warning: Unknown dependency format '$pkg' (use '@aztec/pkg', 'link:pkg:path', or 'npm:pkg')" >&2
+            echo "Warning: Unknown dependency format '$pkg' (use '@aztec/pkg', 'link:pkg:path', 'portal:pkg:path', or 'npm:pkg')" >&2
         fi
     done < <(yq eval '.dependencies[]' "$config_file")
 }

docs/examples/ts/recursive_verification/config.yaml

@@ -19,17 +19,18 @@ dependencies:
   - "@aztec/kv-store"
   - "@aztec/pxe"
   - "@aztec/noir-contracts.js"
-  # Packages outside yarn-project/ - use explicit link paths
-  - "link:@aztec/bb.js:barretenberg/ts/bb.js"
+  # Packages outside yarn-project/. bb.js is pulled via portal: (not link:) so its own runtime deps
+  # (pako, msgpackr, comlink, ...) are installed automatically at the versions bb.js pins — instead of
+  # hand-listing them here, which drifts from bb.js and, left unversioned, floated to a breaking major
+  # (pako 3.0.0 dropped the ESM default export bb.js relies on).
+  - "portal:@aztec/bb.js:barretenberg/ts/bb.js"
   - "link:@aztec/noir-noir_js:noir/packages/noir_js"
   # Transitive dependencies of @aztec/noir-noir_js
   - "link:@aztec/noir-acvm_js:noir/packages/acvm_js"
   - "link:@aztec/noir-noirc_abi:noir/packages/noirc_abi"
   - "link:@aztec/noir-types:noir/packages/types"
-  # Runtime deps of @aztec/bb.js (linked, so its own deps are not auto-installed)
-  - "npm:pako"
-  - "npm:msgpackr"
-  - "npm:comlink"
-  - "npm:idb-keyval"
-  - "npm:commander"
-  - "npm:tslib"
+  # Runtime dep of @aztec/noir-noir_js (used by its debug.mjs). noir_js is link:'d (not portal:'d)
+  # because its @aztec/noir-* deps are pinned to unpublished versions, so portal can't fetch them —
+  # link: does not install a package's own deps, so pako must be supplied here. Pinned to noir_js's
+  # own range (^2.1.0) so it can't float to the breaking pako 3.0.0.
+  - "npm:pako@^2.1.0"