fix(web): repair welcome and repository deep links

Use the reliable built-in ZCode-branded Welcome page instead of a CDN-hosted
webview that cannot establish its isolated origin. Carry repository hash links
through the browser workspace URI so the extension host opens the clone flow,
then render the cloned files in the zcode-opfs Explorer tree.

Author: aaqaishtyaq

PLAN.md

@@ -6,7 +6,7 @@
 | **Repo** | [`github.com/spinupdev/zcode`](https://github.com/spinupdev/zcode) |
 | **Local path** | may still be checked out as `code-server` — product is **ZCode** |
 | **Document purpose** | Handoff for **any agent or engineer**: architecture, how systems connect, **done / in progress / remaining** |
-| **Last updated** | 2026-08-14 (repository deep-link handoff) |
+| **Last updated** | 2026-08-15 (welcome/webview and repository handoff) |
 | **Canonical design RFC** | [`docs/design-dual-mode-vscode-ide.md`](./docs/design-dual-mode-vscode-ide.md) |
 | **VS Code pin** | `1.129.0` → SHA `125df467…` ([`docs/vscode-pin.md`](./docs/vscode-pin.md)) |
 | **Status owner** | Update this file’s **Work tracker** whenever a work package finishes or starts |
@@ -459,5 +459,6 @@ pnpm smoke            # lighter checks
 | 2026-07-27 | **WB8**: shell startup UX — WC prefetch + status bar + progress + auto-open terminal; Pyodide warm status |
 | 2026-07-27 | **WB8 fix**: main-thread `wc-bridge.js` + BroadcastChannel (web EH has no DOM); notification + bridge-based shell |
 | 2026-08-14 | **B8e**: added `zcode-welcome`; VS Code Getting Started is no longer the startup editor, and the ZCode welcome panel only accepts an HTTP(S) Git repository URL |
+| 2026-08-15 | **B8f**: use the reliable built-in Welcome page on CDN-hosted VS Code Web; pass `/#https://...` repository handoffs through transient product configuration so the extension host receives them |
 
 **When you complete work:** set the package **Status** to `done`, add a one-line **Last note** (commit SHA or PR), and append a row to §10.

apps/workbench/scripts/build.mjs

@@ -50,7 +50,6 @@ try {
 }
 
 const zcodeCoreExtensions = [
-  { path: '/extensions/zcode-welcome' },
   { path: '/extensions/zcode-browser-fs' },
   { path: '/extensions/zcode-git' },
   { path: '/extensions/zcode-diagnostics' },
@@ -94,8 +93,8 @@ const defaultProduct = {
     configurationDefaults: {
       'security.workspace.trust.enabled': false,
       'security.workspace.trust.startupPrompt': 'never',
-      // zcode-welcome owns the startup surface; do not open VS Code's Getting Started page.
-      'workbench.startupEditor': 'none',
+      // The built-in Welcome page renders reliably on CDN-hosted VS Code Web.
+      'workbench.startupEditor': 'welcomePage',
       ...themeConfigurationDefaults,
       'files.exclude': {
         '**/.git': true,
@@ -506,6 +505,71 @@ const bootstrap = `/* ZCode workbench bootstrap — load VS Code Web + inject ex
   } catch (_) { /* ignore */ }
 
   window.product = withHostAuthority(window.product || {});
+  // The extension host does not inherit the workbench page's URL fragment.
+  // Pass a safe public repository URL through transient product defaults so
+  // zcode-git can consume hash repository links deterministically.
+  let startupRepository = '';
+  try {
+    const raw = (location.hash || '').slice(1).trim();
+    if (/^https?:\\/\\//i.test(raw)) {
+      const repo = new URL(decodeURIComponent(raw));
+      if (
+        (repo.protocol === 'http:' || repo.protocol === 'https:') &&
+        repo.hostname &&
+        repo.pathname !== '/' &&
+        !repo.username &&
+        !repo.password &&
+        !repo.search &&
+        !repo.hash
+      ) {
+        startupRepository = repo.toString().replace(/#$/, '');
+        history.replaceState(null, '', location.pathname + location.search);
+      }
+    }
+  } catch (_) { /* malformed fragments stay inert */ }
+  if (startupRepository) {
+    if (window.product.folderUri?.scheme === 'zcode-opfs') {
+      const startupBytes = Array.from(new TextEncoder().encode(startupRepository), (byte) =>
+        String.fromCharCode(byte),
+      ).join('');
+      const startupToken = btoa(startupBytes).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');
+      window.product.folderUri = {
+        ...window.product.folderUri,
+        path: '/workspace/__zcode_repo__' + startupToken,
+        query: 'zcodeRepository=' + encodeURIComponent(startupRepository),
+      };
+    }
+    try {
+      sessionStorage.setItem('zcode.startupRepository', startupRepository);
+    } catch (_) { /* private browsing can disable session storage */ }
+    try {
+      // localStorage is shared with the extension-host iframe; consume/remove
+      // this immediately in zcode-git so it remains a one-shot handoff.
+      localStorage.setItem('zcode.startupRepository', startupRepository);
+    } catch (_) { /* private browsing can disable local storage */ }
+    const topDefaults = window.product.configurationDefaults || {};
+    const nestedDefaults = window.product.productConfiguration?.configurationDefaults || {};
+    window.product.configurationDefaults = {
+      ...topDefaults,
+      'zcode.startupRepository': startupRepository,
+    };
+    if (window.product.productConfiguration) {
+      window.product.productConfiguration.configurationDefaults = {
+        ...nestedDefaults,
+        'zcode.startupRepository': startupRepository,
+      };
+    }
+    try {
+      if (typeof BroadcastChannel !== 'undefined') {
+        const channel = new BroadcastChannel('zcode.startup');
+        const message = { type: 'openRepository', url: startupRepository };
+        [0, 500, 1500, 3000].forEach((delay) => {
+          setTimeout(() => channel.postMessage(message), delay);
+        });
+        setTimeout(() => channel.close(), 5000);
+      }
+    } catch (_) { /* extension host can still use product/storage handoff */ }
+  }
   // Walkthrough / markdown webviews must load same-origin (not vscode-cdn.net).
   // Microsoft’s CDN blocks framing from non-Microsoft origins → “content is blocked”.
   const webviewEndpointPath =
@@ -751,7 +815,6 @@ writeFileSync(join(dist, 'bootstrap.js'), bootstrap);
 const extRoot = join(monorepo, 'extensions');
 const extOut = join(dist, 'extensions');
 const productExts = [
-  'zcode-welcome',
   'zcode-browser-fs',
   'zcode-git',
   'zcode-diagnostics',

extensions/zcode-git/package.json

@@ -168,6 +168,11 @@
           "default": "",
           "description": "isomorphic-git corsProxy base URL (empty = same-origin /git-proxy)"
         },
+        "zcode.startupRepository": {
+          "type": "string",
+          "default": "",
+          "description": "Transient repository URL supplied by a ZCode share link"
+        },
         "zcode.gitToken": {
           "type": "string",
           "default": "",

extensions/zcode-git/src/extension.ts

@@ -221,6 +221,55 @@ function readLastWorkspaceId(): string | undefined {
   }
 }
 
+function readStartupRepository(): string | undefined {
+  for (const folder of vscode.workspace.workspaceFolders ?? []) {
+    if (folder.uri.scheme !== SCHEME) continue;
+    const workspaceId = workspaceIdFromFolder(folder.uri);
+    if (workspaceId?.startsWith('__zcode_repo__')) {
+      try {
+        const token = workspaceId.slice('__zcode_repo__'.length).replace(/-/g, '+').replace(/_/g, '/');
+        const padded = token + '='.repeat((4 - (token.length % 4)) % 4);
+        const bytes = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+        const value = new TextDecoder().decode(bytes).trim();
+        if (value) return value;
+      } catch {
+        /* malformed startup workspace token is ignored */
+      }
+    }
+    try {
+      const value = new URLSearchParams(folder.uri.query).get('zcodeRepository')?.trim();
+      if (value) return value;
+    } catch {
+      /* malformed workspace query is ignored */
+    }
+  }
+
+  const configured = vscode.workspace
+    .getConfiguration('zcode')
+    .get<string>('startupRepository')
+    ?.trim();
+  if (configured) return configured;
+  try {
+    const value = globalThis.sessionStorage?.getItem('zcode.startupRepository')?.trim();
+    if (value) {
+      globalThis.sessionStorage?.removeItem('zcode.startupRepository');
+      return value;
+    }
+  } catch {
+    /* private browsing can disable session storage */
+  }
+  try {
+    const value = globalThis.localStorage?.getItem('zcode.startupRepository')?.trim();
+    if (value) {
+      globalThis.localStorage?.removeItem('zcode.startupRepository');
+      return value;
+    }
+  } catch {
+    /* private browsing can disable local storage */
+  }
+  return undefined;
+}
+
 function writeLastWorkspaceId(id: string): void {
   try {
     globalThis.localStorage?.setItem(LAST_WS_KEY, id);
@@ -412,6 +461,7 @@ export function activate(context: vscode.ExtensionContext): void {
 
   let refreshBusy = false;
   let openRepoBusy = false;
+  let startupRepositoryHandled = false;
 
   const ensureWorkspace = async (id: string): Promise<void> => {
     const a = await getAgent();
@@ -893,6 +943,15 @@ export function activate(context: vscode.ExtensionContext): void {
         () => undefined,
       );
 
+      // Workspace URI queries are only available after the provider/workspace
+      // has settled; reading them earlier races VS Code Web startup.
+      const configuredRepository = readStartupRepository();
+      if (configuredRepository) {
+        startupRepositoryHandled = true;
+        await openRepository(configuredRepository);
+        return;
+      }
+
       const hashRepository = repositoryUrlFromHash();
       if (hashRepository) {
         await openRepository(hashRepository);
@@ -944,7 +1003,7 @@ export function activate(context: vscode.ExtensionContext): void {
         return;
       }
 
-      // zcode-welcome owns the empty-workspace startup surface.
+      // The built-in Welcome page owns the empty-workspace startup surface.
       return;
     } catch (err) {
       console.warn('[zcode-git] startup flow', err);
@@ -1076,6 +1135,29 @@ export function activate(context: vscode.ExtensionContext): void {
     }),
   );
 
+  // The workbench page and web extension host do not share URL fragments.
+  // Receive the one-shot deep-link handoff over a same-origin channel.
+  try {
+    if (typeof BroadcastChannel !== 'undefined') {
+      const startupChannel = new BroadcastChannel('zcode.startup');
+      const onStartupMessage = (event: MessageEvent<{ type?: string; url?: string }>) => {
+        const url = event.data?.type === 'openRepository' ? event.data.url?.trim() : undefined;
+        if (!url || startupRepositoryHandled || validateGitUrl(url)) return;
+        startupRepositoryHandled = true;
+        void openRepository(url);
+      };
+      startupChannel.addEventListener('message', onStartupMessage);
+      context.subscriptions.push({
+        dispose: () => {
+          startupChannel.removeEventListener('message', onStartupMessage);
+          startupChannel.close();
+        },
+      });
+    }
+  } catch (err) {
+    console.warn('[zcode-git] startup repository channel unavailable', err);
+  }
+
   void refresh();
   const timer = setInterval(() => void refresh(), 8_000);
   context.subscriptions.push({ dispose: () => clearInterval(timer) });

packages/shell/src/workbench-product.test.ts

@@ -46,10 +46,9 @@ describe('buildWorkbenchCreateOptions', () => {
     assert.equal(o.connectionReady, true);
   });
 
-  it('embeds the ZCode welcome extension and language packs', () => {
+  it('embeds the ZCode browser extensions and language packs', () => {
     const o = buildWorkbenchCreateOptions({ mode: 'browser' });
     const paths = o.additionalBuiltinExtensions?.map((e) => e.path) ?? [];
-    assert.ok(paths.includes('/extensions/zcode-welcome'));
     assert.ok(paths.includes('/extensions/zcode-browser-fs'));
     assert.ok(paths.includes('/extensions/zcode-git'));
     assert.ok(paths.includes('/extensions/zcode-diagnostics'));
@@ -66,7 +65,7 @@ describe('buildWorkbenchCreateOptions', () => {
     assert.ok(paths.includes('/extensions/kotlin'));
     assert.ok(paths.includes('/extensions/solidity'));
     assert.ok(paths.includes('/extensions/zig'));
-    assert.equal(o.productConfiguration.configurationDefaults?.['workbench.startupEditor'], 'none');
+    assert.equal(o.productConfiguration.configurationDefaults?.['workbench.startupEditor'], 'welcomePage');
     // TextMate language packs (syntax highlighting)
     assert.ok(paths.includes('/vscode/extensions/javascript'));
     assert.ok(paths.includes('/vscode/extensions/typescript-basics'));

packages/shell/src/workbench-product.ts

@@ -89,7 +89,6 @@ export interface BuildWorkbenchProductInput {
 
 /** ZCode product extensions under /extensions/* */
 const ZCODE_PRODUCT_EXTENSIONS = [
-  '/extensions/zcode-welcome',
   '/extensions/zcode-browser-fs',
   '/extensions/zcode-git',
   '/extensions/zcode-diagnostics',
@@ -144,9 +143,8 @@ export function configurationDefaultsForMode(
   const base: Record<string, unknown> = {
     'security.workspace.trust.enabled': false,
     'security.workspace.trust.startupPrompt': 'never',
-    // Empty browser workspace — Welcome / Open Repository, not a fake README seed
-    // zcode-welcome owns the startup surface; do not open VS Code's Getting Started page.
-    'workbench.startupEditor': 'none',
+    // Empty browser workspace — built-in Welcome / Open Repository, not a fake README seed.
+    'workbench.startupEditor': 'welcomePage',
     // Built-in theme-defaults + seti (always available under /vscode/extensions)
     'workbench.iconTheme': ZCODE_THEME_DEFAULTS.iconTheme,
     'workbench.colorTheme': ZCODE_THEME_DEFAULTS.colorThemeDark,