Split @mentra/island into main/internal/devtools entry points#3342
Merged
PhilippeFerreiraDeSousa merged 8 commits intoJul 6, 2026
Merged
Conversation
added 5 commits
July 3, 2026 16:13
The third dev sync (f29e401) kept dev's wifi_scan_result listener hunk in the wifi scan screen but dropped its import line during conflict resolution, leaving the branch failing tsc. Import the SDK singleton from @mentra/bluetooth-sdk-internal, matching the other host files that listen to raw SDK events on this branch.
Declare a package exports map with three entries (., ./internal, ./devtools), each with the react-native condition pointing at src so Metro and tooling resolve live TypeScript source, mirroring the @mentra/bluetooth-sdk map. src/internal.ts carries the migration-era runtime surface (raw stores + service singletons); src/devtools.ts carries the debug-only singletons (miniappRunningRegistry, devServerBridge). The main barrel is unchanged in this commit, so both new entries are additive. Jest: resolve the two subpaths to source via moduleNameMapper (like @mentra/bluetooth-sdk-internal) and split the island mock into a lazily built, cached three-entry registry sharing one underlying state. The main mock still spreads the internal + devtools surfaces until the barrel slims down.
Mechanical import split across mobile/src: symbols that expose or mutate runtime state (raw stores, service singletons, runtime wiring, flat OTA/ gallery helpers, BluetoothSdk passthrough, logBuffer, storage, GlobalEventEmitter) now come from @mentra/island/internal; the debug-only singletons (miniappRunningRegistry, devServerBridge) come from @mentra/island/devtools. Host UI keeps plain @mentra/island imports where it only uses toolkit, types, and pure helpers (decide* functions, useApps-style hooks, DUMMY_APPLET, BgTimer, OTA policy constants + deriveDisplayState, readiness predicates, hardware capability tables). The @/stores/* and @/utils/* shims re-export from /internal, so their many importers are unchanged. No statement other than island imports is touched; behavior is identical — the entries resolve the same concrete modules.
The main barrel now exports only the OEM-facing surface: the toolkit namespace, contract/read-model types, and the pure helpers host UI renders with (readiness predicates, connect/reconnect decisions, OTA policy constants and deriveDisplayState, app-list hooks and sort/order helpers, hardware capability tables, BgTimer). Everything store- or service-shaped is reachable only via @mentra/island/internal, and the debug singletons only via @mentra/island/devtools. Also delete the toolkit.stores escape hatch: its five raw stores are already flat exports on the internal entry, its two remaining mentions were shim comments, and its jest mirror goes with it. Module loading is unchanged — toolkit still transitively constructs the same runtime graph — so behavior is identical; this only shrinks the importable API surface.
Add report-only counters for @mentra/island/internal (39 files) and @mentra/island/devtools (2 files) imports in mobile/src, relabel the raw-store counter to reflect that store access now routes through /internal and the @/stores shims (count unchanged at 41), and mark the deleted toolkit.stores hatch as a should-stay-0 counter. Also make report_count survive zero-match patterns under set -euo pipefail — rg exits 1 on no matches, which silently killed the script halfway through the report. Docs: mark integration-review §D phase 4 done with the landed shape, and describe the three entry points in the island README.
PhilippeFerreiraDeSousa
requested review from
AryanFP,
aisraelov and
isaiahb
as code owners
Contributor
📋 PR Review Helper📱 Mobile App Build✅ Ready to test! (commit 🕶️ ASG Client Build⏳ Waiting for build... 🔀 Test Locallygh pr checkout 3342 |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c0224e7dde
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| */ | ||
|
|
||
| // Which miniapps the local runtime currently has running (stress-test screen). | ||
| export {miniappRunningRegistry} from "./services/MiniappRunningRegistry" |
There was a problem hiding this comment.
Moving miniappRunningRegistry exclusively onto /devtools leaves sdk/example-oem-app/App.tsx still importing it from @mentra/island (repo-wide rg '@mentra/island' shows this remaining consumer). When that example is bundled through its Metro alias to mobile/modules/island, the root entry no longer exports the binding, so the example fails to typecheck/bundle before rendering; please repoint the example (and its TS path mapping if needed) to @mentra/island/devtools or keep a compatibility export.
Useful? React with 👍 / 👎.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
2 issues found across 53 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
The example OEM app under sdk/ was the one island consumer outside mobile/src the split missed: it imported miniappRunningRegistry from the main entry, which the slimmed barrel no longer exports. Import it from @mentra/island/devtools, add the matching tsconfig path onto the built devtools types, and note the extra entry in the example README. Verified with a fresh expo-module build of island: the example app typechecks clean and the main .d.ts carries no internal/devtools symbols. Also fix two doc inconsistencies from the same review pass: the island README bullets still described the pre-rename miniappGlobals/devMiniappLaunch exports, and the integration review's 'Present today' escape-hatch list now carries phase-4 disposition brackets so it agrees with the status note above it.
Contributor
Author
|
Addressed all three review-bot findings in 19d287c:
Standard gates re-run after the fix: mobile compile clean, 50 suites/364 tests, island 194 tests, boundary script green (counters unchanged). |
added 2 commits
July 3, 2026 19:09
…t-split Both sides fixed the report_count zero-match abort independently; keep the base's brace-group form so this branch's boundary-script diff reduces to the new entry-point counters. The base now routes streamed wifi scan results through toolkit.glasses.wifi.onScanResult, which removes the raw BluetoothSdk listener from the wifi scan screen — drop the import this branch had restored for it, making the screen identical to the base again.
…x/island-entrypoint-split jest.config.js: keep both sides' island source mappers — the base's new main entry mapping plus this branch's internal/devtools subpath mappings. jest.setup.js: keep the three-entry mock registry and adopt the base's fuller localDisplayManager stub (display-render v1 tests exercise its methods).
Deploying mentra-live-ota-site with
|
| Latest commit: |
6886091
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6dffccd4.mentra-live-ota-site.pages.dev |
| Branch Preview URL: | https://codex-island-entrypoint-spli.mentra-live-ota-site.pages.dev |
Deploying mentra-store-dev with
|
| Latest commit: |
6886091
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://17edfef5.augmentos-appstore-2.pages.dev |
| Branch Preview URL: | https://codex-island-entrypoint-spli.augmentos-appstore-2.pages.dev |
Deploying dev-augmentos-console with
|
| Latest commit: |
6886091
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6ff4d032.dev-augmentos-console.pages.dev |
| Branch Preview URL: | https://codex-island-entrypoint-spli.dev-augmentos-console.pages.dev |
Deploying prod-augmentos-account with
|
| Latest commit: |
6886091
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6ed9c421.augmentos-e84.pages.dev |
| Branch Preview URL: | https://codex-island-entrypoint-spli.augmentos-e84.pages.dev |
PhilippeFerreiraDeSousa
merged commit 8050a95
into
integration/toolkit-boundary
24 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 4 of the 020 integration review (
cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md§D): split@mentra/islandinto three entry points and repoint every host import. Pure module topology — zero runtime behavior change. The entries resolve the same concrete modules, so every singleton stays single and module-load side effects (e.g.PhoneLocationService's background-task registration, which the toolkit graph still loads transitively) keep their timing.What moved where
@mentra/island(main)toolkit(configure/start/stop + facades), contract/read-model types (OTA, gallery, reports, runtime DTOs,ClientApp+ hardware tables), and pure helpers host UI renders with:decideReconnect/decideConnectButtonAction, readiness predicates,deriveDisplayState+ OTA policy constants (OtaProgressMessages,MINIMUM_OTA_STATUS_BUILD, …), theuseApps-style hook layer + sort/order helpers +DUMMY_APPLET,decideDevLaunchRoute,HardwareCompatibility,MediaLibraryPermissions,BgTimer/throttle/debounce,WebSocketStatus@mentra/island/internaluseCoreStore,useDisplayStore,useConnectionStore,useCloudClientStatusStore,useSettingsStore/useSetting/SETTINGS,useAppStatusStore+installAppStoreHooks) and service singletons:appRegistrycluster (incl. dev-app registration),cloudClientService,restComms,cloudSecureStore, gallery cluster (gallerySyncService,asgCameraApi,localStorageService,mediaProcessingQueue,gallerySettingsService, validation + notices), miniapp engine cluster (routers, launcher,localMiniappRuntime, webview shim/globals builders),displayProcessor,navigationService,audioPlaybackService, phone coordinators +phoneLocationService, STT/TTS model managers, flat OTA check helpers + clock fixes,logBuffer,storage,GlobalEventEmitter,BluetoothSdkpassthrough,configureRuntime/getRuntimeHooks@mentra/island/devtoolsminiappRunningRegistry,devServerBridgeJudgment rule (from the task/§D): read models, commands, pure functions, and types = main; anything that mutates runtime state or exposes a store/service = not main. Refinement applied: types travel with the surface they describe (e.g.
RuntimeSnapshottypes live with the internal store;GalleryNoticestays main because it typestoolkit.gallery.onNotice), and pure helpers that only serve an internal cluster (manifest normalizers, gallery-sync clock utils, webview script builders) stay with their cluster instead of widening main.toolkit.stores.*is deleted fromisland.ts— its five stores were already flat exports on/internal, and the "2 remaining users" the boundary counter reported were comment mentions in the@/stores/{core,connection}shims (updated).Mechanics
package.jsonexportsmap mirrors the bluetooth-sdk precedent:types→build/*.d.ts,react-native→src/*.ts(so Metro/jest/tsc resolve live source, no build-staleness),default→build/*.js;./src/*and./build/*blocked. Metro's existing root hook is untouched; subpaths resolve via the exports map exactly like@mentra/bluetooth-sdk/internalalready does in this app.@mentra/island/*path wildcard covers the new subpaths.moduleNameMapperpins both subpaths to source (mirroring@mentra/bluetooth-sdk-internal), and the island mock became a lazily built, cached three-entry registry sharing one underlying state — key sets mirror the real entry partition.mobile/srcchanged).@/stores/*and@/utils/*shims re-export from/internal, so their ~150 importers are untouched./internaland/devtoolsimports; raw-store counter relabeled (store access now routes through/internal+ shims — pattern kept for metric continuity);report_countfixed to survive zero-match patterns underset -euo pipefail.BluetoothSdkimport inwifi/scan.tsxthat the third dev-sync merge dropped (baselinetscwas failing on this branch).Boundary counters (before → after)
@mentra/island/internalimporters@mentra/island/devtoolsimporterstoolkit.storesescape hatchwifi/scan.tsxfix)Test evidence
cd mobile && bun run compile— clean (baseline was failing; fixed in the first commit)cd mobile && bun run test— 50 suites / 364 tests pass (= baseline)cd mobile/modules/island && bun run test— 194 tests pass (= baseline)./scripts/check-mobile-runtime-boundary.sh— passes, counters aboveNotes
integration/toolkit-boundary(Land the toolkit boundary stack: island facades, Cloud V2 reports, dev merge + review fixes #3331); this PR retargets todevautomatically when Land the toolkit boundary stack: island facades, Cloud V2 reports, dev merge + review fixes #3331 merges.toolkit.pairing, display →toolkit.display.mirror, session, miniapps hooks, settings) stays open; the new/internalcounter is its ratchet.Note
Low Risk
Import-path and export-surface refactor with no intended runtime behavior change; risk is limited to mis-partitioned exports or broken resolution in Metro/jest/tsc.
Overview
Phase 4 (020 §D) splits
@mentra/islandinto three package entry points so OEM-facing imports stay narrow while the Mentra host keeps a migration path to raw runtime APIs.@mentra/islandis trimmed totoolkit, contract/read-model types, and pure UI helpers (hooks likeuseApps, OTA policy constants,decideReconnect, etc.).@mentra/island/internalholds zustand stores and service singletons (appRegistry,restComms, gallery cluster, miniapp engine, flat OTA check helpers).@mentra/island/devtoolsexposesminiappRunningRegistryanddevServerBridge.package.jsonexports(withreact-native→src/) and newinternal.ts/devtools.tsbarrels implement the split;toolkit.stores.*is removed fromisland.ts.Host code and
@/stores/*/@/utils/*shims now import stores and services from/internal(and dev screens from/devtools) instead of the main barrel. Jest maps all three entries to source and uses one cached three-way mock;check-mobile-runtime-boundary.shadds report-only/internaland/devtoolsimport counts. Island README, integration-review §D, and the example OEM app are updated to match.Reviewed by Cursor Bugbot for commit 6886091. Bugbot is set up for automated code reviews on this repo. Configure here.