wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28_NOTES.md

@@ -136,6 +136,9 @@ The standalone `protocol-demonstration` runtime must not import UAPI or commerci
 V28 closes this as a boundary baseline; V29 must continue commercializing freshly ported protocol internals into cleaner packages and narrower APIs.
 Dual-lane setup smoke also found that the embedded demonstration witness could overwrite the commercial Terminal browser title with `Bitcode Demonstration`.
 That is a commercial/demonstration boundary leak, so V28 now requires the mounted witness bundle to guard document-title writes when hosted inside `/terminal`; standalone demonstration may keep its demonstration title.
+The same deployment-readiness pass found a Vercel production build failure in `lib/bitcode-app-context.ts` because the newly formalized `@bitcode/protocol` package was present as a workspace dependency but had not been added to the Next transpilation/webpack alias path.
+V28 treats this as a commercial MVP blocker: formal protocol package imports must resolve during local and Vercel `next build`.
+The UAPI Next configuration now transpiles `@bitcode/protocol`, aliases its root import to `packages/protocol/src/index.js`, and the commercial protocol boundary test asserts this resolver so the standalone demonstration separation remains deployable.
 
 Manual QA was re-ordered on May 8, 2026 into two directionalities.
 The first is natural operator progression: connect wallet/GitHub/identity prerequisites, perform the fastest simple Need through Fit/settlement/delivery readback, then perform the fastest simple Give through measurement/earning/settlement readback.
@@ -148,6 +151,21 @@ The Mock lane runs first with deterministic mocks enabled so visual behavior, co
 The Testnet-readiness lane follows with public mock flags disabled and `NEXT_PUBLIC_BITCODE_ENV=testnet`, preserving Exchange/Auxillaries/Create Account entry while exposing real provider, signer, GitHub, database, BTC broadcaster, ledger observer, and interface readiness.
 V28 does not require that every live credential already be provisioned, but it does require that missing live/testnet dependencies fail closed with readable readiness rather than silent mocked success.
 This dual-lane process is intentionally earlier than V34 deployment deepening: it guards V28 MVP QA against mock-only confidence while leaving production deployment, host capabilities, distributed execution, CI/CD promotion, and operational rollback to V34.
+The first restarted 1A mock-lane pass showed a readiness/cache edge case: Auxillaries indicated mock mode, but the top chrome rendered zero BTC/BTD and an empty notification tray after prior mock values had been visible.
+V28 closes this as an MVP QA bug, not a user-data polish item.
+Master mock mode must activate auxillaries mock data consistently in client and server code, public mock flags must be visible to the Next client bundle, and shared user-data cache must revalidate on fresh mounts so environment-lane changes cannot preserve anonymous or zero-valued state.
+The same 1A verification also found that simultaneous mock and testnet-readiness dev servers must not share the same Next build artifact directory.
+V28 QA therefore requires lane-specific `NEXT_DIST_DIR` values for local dual-lane runs, because the client bundle compiles public env values while the server routes read process env at request time.
+Without isolated artifacts, the testnet-readiness lane can appear mock-authenticated even while its `/api/auxillaries/data` response correctly returns anonymous zero-state.
+
+The next 1A Auxillaries/Profile/Connects slice exposed four MVP shell issues and closed them in source and tests.
+The active contained pane must own vertical scrolling; the overlay shell may constrain height, but it must not trap the operator above lower profile, wallet, or repository controls.
+Selector-card state must render as visual indicators rather than `laneactive` / `laneready` prose, while retaining accessible labels and machine-readable state for tests.
+Async profile props must hydrate into editable local fields after mock/live data arrives, so display name, bio, company, avatar, and team data do not remain blank after the email field has already loaded.
+The BTC/BTD widget must render a compact wallet-reading posture while fresh lane-specific data loads or while stale anonymous zero-state is being revalidated; zero BTC/BTD may be shown only as a settled data state, not as an unceremonious hydration flash.
+
+These changes remain V28 scope because they are MVP-readiness and trust issues.
+The deeper Auxillaries version retains hierarchy, spacing, diagnostics, recovery, and provider-management expansion after V28 proves the contained shell, mocked prerequisite reads, fail-closed testnet-readiness, and no-console-error baseline.
 
 ## Promotion Review Basis
 

BITCODE_V28_QA.md

@@ -171,6 +171,33 @@ Implemented after Pass 2, pending next manual QA confirmation:
 | Testnet-readiness | `http://127.0.0.1:3001/terminal` | renders HTTP 200 after cold compile | Server runs with public mock flags disabled and `NEXT_PUBLIC_BITCODE_ENV=testnet`; missing live credentials/providers are expected to appear as blocked readiness, not success. |
 | Both | `/terminal` browser title | pass | Follow-up smoke confirms both lanes keep the commercial `Bitcode Terminal` document title after the embedded witness title guard. |
 | Both | 2026-05-08 dev-server restart for Pass 3A | pass | Mock server restarted on `3000`; testnet-readiness server restarted on `3001`; curl and Playwright smoke confirm `/terminal` HTTP 200, `Bitcode Terminal` title, no page errors, and no non-HMR internal 404s after reload. |
+| Vercel deployment build | pass after fix | Latest deployment failed because `lib/bitcode-app-context.ts` imported `@bitcode/protocol` before Next's workspace-package resolver knew how to transpile/alias the new formal protocol package. V28 now adds `@bitcode/protocol` to `transpilePackages`, aliases the root import to `packages/protocol/src/index.js`, and verifies the resolver in `tests/protocolCommercialBoundary.test.ts`. Local `pnpm run build` from `uapi` now passes. |
+| Mock top chrome during 1A | pass | Manual reconfirmation on 2026-05-08 accepted the fixed mock balance, notification, and profile posture. V28 now treats master mock mode as sufficient for auxillaries mock data in client and server code, explicitly exposes public mock flags through Next config, and revalidates stale module-level user data on new mount so lane transitions cannot keep anonymous/zero cached data. |
+| Dual-lane dev artifact isolation | pass | Manual reconfirmation on 2026-05-08 accepted the mock/testnet-readiness separation. V28 QA servers use lane-specific `NEXT_DIST_DIR` values so public mock env compilation is isolated per lane. |
+
+### 2026-05-08 Pass 3A: Auxillaries Profile And Connects Readiness
+
+| Check | Result | Notes |
+| --- | --- | --- |
+| Auxillaries overlay opens and pane selection works | pass | Manual QA confirmed the overlay opens and panes remain selectable. |
+| Inner pane scrolling | fixed | Manual QA found the contained pane could not scroll down. V28 now constrains the overlay shell height, keeps the pane as the scroll container, and verifies the active pane can advance `scrollTop` with `overflowY:auto`. |
+| Selector card state rendering | fixed | Manual QA found raw `laneactive` / `laneready` text. V28 replaces visible state prose with active/ready/locked visual indicators and keeps state available through `aria-label`, `title`, and `data-state` for accessibility and tests. |
+| Mock profile fields | fixed | Manual QA confirmed email but found display name and bio missing. V28 now hydrates async initial profile props into local editable state and mock data supplies display name, bio, and company posture. |
+| Connected repositories | pass | Manual QA confirmed mocked connected repos; browser verification confirms `Connected Repositories (3)` and `bitcode/economic-ledger` render in Connects. |
+| BTD/BTC first-load posture | fixed | Manual QA found the top-right widget flashing anonymous zero-state before hydrated values. V28 now surfaces a compact `Reading wallet` posture while fresh lane-specific user data is loading or revalidating stale cached zero-state. |
+| Console/page errors | pass | Manual QA reported none; focused browser verification reports no product console messages and no page errors. |
+
+Automated verification for this slice:
+
+- `pnpm -C uapi exec jest --runInBand tests/useUserDataHydration.test.tsx tests/btdTrackerLoading.test.tsx tests/auxillariesWorkspacePanels.test.tsx tests/featureFlagsMockMode.test.ts`: pass.
+- `pnpm -C uapi exec playwright test tests/e2e/commercial-mvp.auxillaries.spec.ts --project=laptop --workers=1`: 8 passed.
+- Focused browser verification on the mock lane: raw lane text count `0`, state indicator count `4`, Profile display name `Avery Mercer`, Profile bio `Reviewing the Bitcode commercial surface in deterministic mock mode.`, pane `scrollTop` advances, Connects repos present, no product console/page errors.
+
+Deferred to V31 from this pass:
+
+| Finding | V31 disposition |
+| --- | --- |
+| Auxillaries pane hierarchy, spacing, border polish, readiness recovery, and account/provider diagnostics can deepen beyond the V28 MVP shell. | V31 owns full Auxillaries deepening after V28 proves the contained shell, pane selectability, mocked prerequisites, and fail-closed readiness posture. |
 
 Ignored during this setup smoke: Google Analytics network aborts in headless Playwright.
 They are external telemetry noise, not product readiness evidence.
@@ -187,6 +214,8 @@ Automated verification after this implementation pass:
 - `pnpm -C packages/protocol test`: 1 passed after the formal package split.
 - `pnpm -C packages/protocol run typecheck`: pass after adding the formal package typecheck config.
 - `pnpm -C uapi exec jest --runInBand tests/protocolCommercialBoundary.test.ts`: 3 passed after the formal package split.
+- `pnpm -C uapi exec jest --runInBand tests/useUserDataHydration.test.tsx tests/featureFlagsMockMode.test.ts tests/protocolCommercialBoundary.test.ts`: 11 passed after the mock top-chrome cache/flag fix, JavaScript companion parity check, and protocol package resolver check.
+- Playwright dual-lane browser verification after lane-specific `NEXT_DIST_DIR` restart: mock lane shows `0.042 BTC`, `1,200 BTD`, mock review state, reviewer profile, and populated notifications; testnet-readiness lane shows no mock balances, no mock review state, and the Connect Wallet prerequisite controls; both lanes have no product console/page errors.
 
 Deferred to V29 from this pass:
 
@@ -208,6 +237,7 @@ Mock lane dev server:
 
 ```sh
 NEXT_PUBLIC_MASTER_MOCK_MODE=true \
+NEXT_DIST_DIR=.next-v28-mock \
 NEXT_PUBLIC_ENABLE_MOCKS=true \
 NEXT_PUBLIC_MOCK_USER_AUXILLARIES=true \
 NEXT_PUBLIC_MOCK_USER_AUXILLARIES_SCENARIO=demo \
@@ -225,6 +255,7 @@ Testnet-readiness lane dev server:
 
 ```sh
 NEXT_PUBLIC_BITCODE_ENV=testnet \
+NEXT_DIST_DIR=.next-v28-testnet \
 NEXT_PUBLIC_MASTER_MOCK_MODE=false \
 NEXT_PUBLIC_ENABLE_MOCKS=false \
 NEXT_PUBLIC_MOCK_USER_AUXILLARIES=false \

uapi/.gitignore

@@ -11,6 +11,7 @@
 
 # next.js
 /.next/
+/.next-*/
 /out/
 
 # production

uapi/app/auxillaries/components/AuxillariesProfilePane.tsx

@@ -293,6 +293,26 @@ export default function AuxillariesProfilePane({ onSave,
   const [selectedAvatar, setSelectedAvatar] = useState(0);
   const [showAvatarSelector, setShowAvatarSelector] = useState(false);
 
+  useEffect(() => {
+    _setUsername(initialUsername);
+  }, [initialUsername]);
+
+  useEffect(() => {
+    setDisplayName(initialDisplayName);
+  }, [initialDisplayName]);
+
+  useEffect(() => {
+    setBio(initialBio);
+  }, [initialBio]);
+
+  useEffect(() => {
+    setCompanyName(initialCompanyName);
+  }, [initialCompanyName]);
+
+  useEffect(() => {
+    setAvatarUrl(initialAvatarUrl);
+  }, [initialAvatarUrl]);
+
   useEffect(() => {
     setWalletAddress(initialWalletAddress);
     setWalletProvider(initialWalletProvider || (initialWalletAddress ? 'manual' : ''));
@@ -321,6 +341,11 @@ export default function AuxillariesProfilePane({ onSave,
   );
   const [teamSectionExpanded, setTeamSectionExpanded] = useState(false);
 
+  useEffect(() => {
+    if (initialTeamMembers.length === 0) return;
+    setTeamMembers(initialTeamMembers);
+  }, [initialTeamMembers]);
+
   // Sample avatar options
   const avatarOptions = AVATAR_OPTIONS;
 

uapi/app/auxillaries/components/shared/AuxillariesWorkspacePanels.tsx

@@ -33,6 +33,13 @@ export default function AuxillariesWorkspacePanels({
         const descriptor = getAuxillaryDescriptor(step);
         const isActive = currentStep === step;
         const isAvailable = availableSteps.includes(step);
+        const state = isActive ? 'active' : isAvailable ? 'ready' : 'locked';
+        const stateLabel =
+          state === 'active'
+            ? 'Active auxillary'
+            : state === 'ready'
+              ? 'Ready auxillary'
+              : 'Locked auxillary';
 
         return (
           <div key={step} role="listitem">
@@ -57,9 +64,12 @@ export default function AuxillariesWorkspacePanels({
                 <span className="orbital-workspace-panel-layer auxillaries-bitcode-selector-card-layer">
                   {getAuxillaryLayerLabel(step)}
                 </span>
-                <span className="orbital-workspace-panel-state auxillaries-bitcode-selector-card-state">
-                  {isActive ? 'active' : isAvailable ? 'ready' : 'locked'}
-                </span>
+                <span
+                  className={`orbital-workspace-panel-state auxillaries-bitcode-selector-card-state auxillaries-bitcode-selector-card-state-${state}`}
+                  aria-label={stateLabel}
+                  title={stateLabel}
+                  data-state={state}
+                />
               </div>
               <p className="orbital-workspace-panel-label auxillaries-bitcode-selector-card-label">
                 {descriptor.label}

uapi/components/base/bitcode/btd/btd-tracker.tsx

@@ -1,7 +1,7 @@
 
 'use client';
 
-import { useEffect, useState, useMemo, useRef, useLayoutEffect } from 'react';
+import React, { useEffect, useState, useMemo, useRef, useLayoutEffect } from 'react';
 import { useAuth } from '@/components/base/bitcode/auth/AuthProvider';
 import Logo from '@/components/base/bitcode/branding/logo';
 import { motion, AnimatePresence } from 'framer-motion';
@@ -18,6 +18,7 @@ interface BTDTrackerProps {
   btdBalance: number;
   btcFeeBalance?: number | null;
   recentBtdAssetPacks?: BtdAssetPackSummary[];
+  isLoading?: boolean;
 }
 
 function formatBtcFeeBalance(balance: number | null | undefined) {
@@ -53,16 +54,18 @@ export function BTDTracker({
   btdBalance,
   btcFeeBalance = null,
   recentBtdAssetPacks = [],
+  isLoading = false,
 }: BTDTrackerProps) {
   const [displayedBtdBalance, setDisplayedBtdBalance] = useState(btdBalance);
   const [displayedBtcFeeBalance, setDisplayedBtcFeeBalance] = useState<number | null>(btcFeeBalance);
   const [isHovered, setIsHovered] = useState(false);
   const [isAnimating, setIsAnimating] = useState(false);
   const [exchangeState, setExchangeState] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
-  const shouldShowExchangeNow = isHovered;
+  const isBalanceLoading = isLoading && btdBalance === 0 && btcFeeBalance === null;
+  const shouldShowExchangeNow = isHovered && !isBalanceLoading;
   const btcBalanceLabel = formatBtcFeeBalance(displayedBtcFeeBalance);
   const btdBalanceLabel = `${displayedBtdBalance.toLocaleString()} BTD`;
-  const balanceLabel = `${btcBalanceLabel}; ${btdBalanceLabel}`;
+  const balanceLabel = isBalanceLoading ? 'Reading BTC and BTD wallet posture' : `${btcBalanceLabel}; ${btdBalanceLabel}`;
   const recentAssetPackTitle = useMemo(() => {
     const labels = recentBtdAssetPacks
       .slice(0, 5)
@@ -76,14 +79,16 @@ export function BTDTracker({
   // Measure the widest hover/rest posture so the tracker does not resize on hover.
   const exchangeRef = useRef<HTMLSpanElement>(null);
   const btdRef = useRef<HTMLSpanElement>(null);
+  const loadingRef = useRef<HTMLSpanElement>(null);
   const [textWidth, setTextWidth] = useState(0);
   useLayoutEffect(() => {
-    if (exchangeRef.current && btdRef.current) {
+    if (exchangeRef.current && btdRef.current && loadingRef.current) {
       const exchangeW = exchangeRef.current.offsetWidth;
       const btdW = btdRef.current.offsetWidth;
-      setTextWidth(Math.ceil(Math.max(exchangeW, btdW)));
+      const loadingW = loadingRef.current.offsetWidth;
+      setTextWidth(Math.ceil(Math.max(exchangeW, btdW, loadingW)));
     }
-  }, [displayedBtcFeeBalance, displayedBtdBalance]);
+  }, [displayedBtcFeeBalance, displayedBtdBalance, isBalanceLoading]);
   // Compute static container min-width: icon + gap + text + horizontal paddings
   const paddingPx = 24; // px-6
   const iconWidthPx = 16; // w-4
@@ -318,6 +323,7 @@ export function BTDTracker({
           {/* Hidden measurement spans */}
           <div style={{ position: 'absolute', visibility: 'hidden', pointerEvents: 'none' }}>
             <span ref={exchangeRef} className="whitespace-nowrap font-normal tracking-wide text-sm">Exchange BTD</span>
+            <span ref={loadingRef} className="whitespace-nowrap font-normal tracking-wide text-sm">Reading wallet</span>
             <span ref={btdRef} className="inline-flex items-center whitespace-nowrap font-medium tracking-wide text-sm">
               <span>{btcBalanceLabel}</span>
               <span
@@ -377,6 +383,21 @@ export function BTDTracker({
                 exit={{ opacity: 0, rotateX: 90 }}
                 transition={{ duration: 0.3, ease: 'easeInOut' }}
               >Opening Exchange...</motion.span>
+            ) : isBalanceLoading ? (
+              <motion.span
+                key="wallet-loading"
+                className="inline-flex w-full items-center justify-center gap-2 whitespace-nowrap font-normal tracking-wide text-sm text-emerald-200/78"
+                initial={{ opacity: 0, rotateX: -90 }}
+                animate={{ opacity: 1, rotateX: 0 }}
+                exit={{ opacity: 0, rotateX: 90 }}
+                transition={{ duration: 0.3, ease: 'easeInOut' }}
+              >
+                <span
+                  aria-hidden="true"
+                  className="inline-block h-1.5 w-1.5 rounded-full bg-emerald-200/80 shadow-[0_0_10px_rgba(103,254,183,0.45)]"
+                />
+                <span>Reading wallet</span>
+              </motion.span>
             ) : exchangeState === 'idle' && shouldShowExchangeNow ? (
               <motion.span
                 key="exchange"

uapi/components/base/bitcode/layout/nav.tsx

@@ -84,7 +84,13 @@ export default function Nav() {
   const pathname = usePathname();
   const router = useRouter();
   const { user } = useAuth();
-  const { btdBalance, btcFeeBalance, recentBtdAssetPacks } = useUserData();
+  const {
+    btdBalance,
+    btcFeeBalance,
+    recentBtdAssetPacks,
+    isLoading: isUserDataLoading,
+    isRevalidating: isUserDataRevalidating,
+  } = useUserData();
 
   const [showNavUse, setShowNavUse] = useState(false);
   const [showNavEntrance, setShowNavEntrance] = useState(navEntrancePlayedInRuntime);
@@ -489,6 +495,7 @@ export default function Nav() {
                     btdBalance={btdBalance}
                     btcFeeBalance={btcFeeBalance}
                     recentBtdAssetPacks={recentBtdAssetPacks}
+                    isLoading={isUserDataLoading || isUserDataRevalidating}
                   />
                 )}