ci & conflict

Author: eryue0220

.github/workflows/mirror-tangled.yml

@@ -13,6 +13,7 @@ permissions:
 jobs:
   mirror:
     name: 🕸️ Mirror to Tangled
+    if: ${{ github.repository == 'npmx-dev/npmx.dev' }}
     runs-on: ubuntu-24.04-arm
 
     steps:

.gitignore

@@ -40,6 +40,7 @@ test-results/
 
 # generated files
 shared/types/lexicons
+file-tree-sprite.svg
 
 **/__screenshots__/**
 

.lighthouserc.cjs

@@ -35,14 +35,18 @@ module.exports = {
       chromePath: findChrome(),
       puppeteerScript: './lighthouse-setup.cjs',
       settings: {
-        onlyCategories: ['accessibility'],
+        onlyCategories: process.env.LH_PERF ? ['performance'] : ['accessibility'],
         skipAudits: ['valid-source-maps'],
       },
     },
     assert: {
-      assertions: {
-        'categories:accessibility': ['error', { minScore: 1 }],
-      },
+      assertions: process.env.LH_PERF
+        ? {
+            'cumulative-layout-shift': ['error', { maxNumericValue: 0 }],
+          }
+        : {
+            'categories:accessibility': ['error', { minScore: 1 }],
+          },
     },
     upload: {
       target: 'temporary-public-storage',

.oxfmtignore

@@ -33,6 +33,7 @@ This focus helps guide our project decisions as a community and what we choose t
   - [Available commands](#available-commands)
   - [Project structure](#project-structure)
   - [Local connector CLI](#local-connector-cli)
+  - [Mock connector (for local development)](#mock-connector-for-local-development)
 - [Code style](#code-style)
   - [TypeScript](#typescript)
   - [Server API patterns](#server-api-patterns)
@@ -54,6 +55,7 @@ This focus helps guide our project decisions as a community and what we choose t
   - [Unit tests](#unit-tests)
   - [Component accessibility tests](#component-accessibility-tests)
   - [Lighthouse accessibility tests](#lighthouse-accessibility-tests)
+  - [Lighthouse performance tests](#lighthouse-performance-tests)
   - [End to end tests](#end-to-end-tests)
   - [Test fixtures (mocking external APIs)](#test-fixtures-mocking-external-apis)
 - [Submitting changes](#submitting-changes)
@@ -103,6 +105,10 @@ pnpm dev              # Start development server
 pnpm build            # Production build
 pnpm preview          # Preview production build
 
+# Connector
+pnpm npmx-connector   # Start the real connector (requires npm login)
+pnpm mock-connector   # Start the mock connector (no npm login needed)
+
 # Code Quality
 pnpm lint             # Run linter (oxlint + oxfmt)
 pnpm lint:fix         # Auto-fix lint issues
@@ -114,6 +120,7 @@ pnpm test:unit        # Unit tests only
 pnpm test:nuxt        # Nuxt component tests
 pnpm test:browser     # Playwright E2E tests
 pnpm test:a11y        # Lighthouse accessibility audits
+pnpm test:perf        # Lighthouse performance audits (CLS)
 ```
 
 ### Project structure
@@ -155,6 +162,36 @@ pnpm npmx-connector
 
 The connector will check your npm authentication, generate a connection token, and listen for requests from npmx.dev.
 
+### Mock connector (for local development)
+
+If you're working on admin features (org management, package access controls, operations queue) and don't want to use your real npm account, you can run the mock connector instead:
+
+```bash
+pnpm mock-connector
+```
+
+This starts a mock connector server pre-populated with sample data (orgs, teams, members, packages). No npm login is required — operations succeed immediately without making real npm CLI calls.
+
+The mock connector prints a connection URL to the terminal, just like the real connector. Click it (or paste the token manually) to connect the UI.
+
+**Options:**
+
+```bash
+pnpm mock-connector                # default: port 31415, user "mock-user", sample data
+pnpm mock-connector --port 9999    # custom port
+pnpm mock-connector --user alice   # custom username
+pnpm mock-connector --empty        # start with no pre-populated data
+```
+
+**Default sample data:**
+
+- **@nuxt**: 4 members (mock-user, danielroe, pi0, antfu), 3 teams (core, docs, triage)
+- **@unjs**: 2 members (mock-user, pi0), 1 team (maintainers)
+- **Packages**: @nuxt/kit, @nuxt/schema, @unjs/nitro with team-based access controls
+
+> [!TIP]
+> Run `pnpm dev` in a separate terminal to start the Nuxt dev server, then click the connection URL from the mock connector to connect.
+
 ## Code style
 
 When committing changes, try to keep an eye out for unintended formatting updates. These can make a pull request look noisier than it really is and slow down the review process. Sometimes IDEs automatically reformat files on save, which can unintentionally introduce extra changes.
@@ -379,7 +416,7 @@ npmx.dev uses [@nuxtjs/i18n](https://i18n.nuxtjs.org/) for internationalization.
 - All user-facing strings should use translation keys via `$t()` in templates and script
 - Translation files live in [`i18n/locales/`](i18n/locales) (e.g., `en-US.json`)
 - We use the `no_prefix` strategy (no `/en-US/` or `/fr-FR/` in URLs)
-- Locale preference is stored in cookies and respected on subsequent visits
+- Locale preference is stored in `localStorage` and respected on subsequent visits
 
 ### i18n commands
 
@@ -641,18 +678,38 @@ pnpm test:a11y:prebuilt
 
 # Or run a single color mode manually
 pnpm build:test
-LIGHTHOUSE_COLOR_MODE=dark ./scripts/lighthouse-a11y.sh
+LIGHTHOUSE_COLOR_MODE=dark ./scripts/lighthouse.sh
 ```
 
 This requires Chrome or Chromium to be installed. The script will auto-detect common installation paths. Results are printed to the terminal and saved in `.lighthouseci/`.
 
 #### Configuration
 
-| File                         | Purpose                                                   |
-| ---------------------------- | --------------------------------------------------------- |
-| `.lighthouserc.cjs`          | Lighthouse CI config (URLs, assertions, Chrome path)      |
-| `lighthouse-setup.cjs`       | Puppeteer script for color mode + client-side API mocking |
-| `scripts/lighthouse-a11y.sh` | Shell wrapper that runs the audit for a given color mode  |
+| File                    | Purpose                                                   |
+| ----------------------- | --------------------------------------------------------- |
+| `.lighthouserc.cjs`     | Lighthouse CI config (URLs, assertions, Chrome path)      |
+| `lighthouse-setup.cjs`  | Puppeteer script for color mode + client-side API mocking |
+| `scripts/lighthouse.sh` | Shell wrapper that runs the audit for a given color mode  |
+
+### Lighthouse performance tests
+
+The project also runs Lighthouse performance audits to enforce zero Cumulative Layout Shift (CLS). These run separately from the accessibility audits and test the same set of URLs.
+
+#### How it works
+
+The same `.lighthouserc.cjs` config is shared between accessibility and performance audits. When the `LH_PERF` environment variable is set, the config switches from the `accessibility` category to the `performance` category and asserts that CLS is exactly 0.
+
+#### Running locally
+
+```bash
+# Build + run performance audit
+pnpm test:perf
+
+# Or against an existing test build
+pnpm test:perf:prebuilt
+```
+
+Unlike the accessibility audits, performance audits do not run in separate light/dark modes.
 
 ### End to end tests
 
@@ -730,6 +787,74 @@ You need to either:
 1. Add a fixture file for that package/endpoint
 2. Update the mock handlers in `test/fixtures/mock-routes.cjs` (client) or `modules/runtime/server/cache.ts` (server)
 
+### Testing connector features
+
+Features that require authentication through the local connector (org management, package collaborators, operations queue) are tested using a mock connector server.
+
+#### Architecture
+
+The mock connector infrastructure is shared between the CLI, E2E tests, and Vitest component tests:
+
+```
+cli/src/
+├── types.ts           # ConnectorEndpoints contract (shared by real + mock)
+├── mock-state.ts      # MockConnectorStateManager (canonical source)
+├── mock-app.ts        # H3 mock app + MockConnectorServer class
+└── mock-server.ts     # CLI entry point (pnpm mock-connector)
+
+test/test-utils/       # Re-exports from cli/src/ for test convenience
+test/e2e/helpers/      # E2E-specific wrappers (fixtures, global setup)
+```
+
+Both the real server (`cli/src/server.ts`) and the mock server (`cli/src/mock-app.ts`) conform to the `ConnectorEndpoints` interface defined in `cli/src/types.ts`. This ensures the API contract is enforced by TypeScript. When adding a new endpoint, update `ConnectorEndpoints` first, then implement it in both servers.
+
+#### Vitest component tests (`test/nuxt/`)
+
+- Mock the `useConnector` composable with reactive state
+- Use `document.body` queries for components using Teleport
+- See `test/nuxt/components/HeaderConnectorModal.spec.ts` for an example
+
+```typescript
+// Create mock state
+const mockState = ref({ connected: false, npmUser: null, ... })
+
+// Mock the composable
+vi.mock('~/composables/useConnector', () => ({
+  useConnector: () => ({
+    isConnected: computed(() => mockState.value.connected),
+    // ... other properties
+  }),
+}))
+```
+
+#### Playwright E2E tests (`test/e2e/`)
+
+- A mock HTTP server starts automatically via Playwright's global setup
+- Use the `mockConnector` fixture to set up test data and the `gotoConnected` helper to navigate with authentication
+
+```typescript
+test('shows org members', async ({ page, gotoConnected, mockConnector }) => {
+  // Set up test data
+  await mockConnector.setOrgData('@testorg', {
+    users: { testuser: 'owner', member1: 'admin' },
+  })
+
+  // Navigate with connector authentication
+  await gotoConnected('/@testorg')
+
+  // Test assertions
+  await expect(page.getByRole('link', { name: '@testuser' })).toBeVisible()
+})
+```
+
+The mock connector supports test endpoints for state manipulation:
+
+- `/__test__/reset` - Reset all mock state
+- `/__test__/org` - Set org users, teams, and team members
+- `/__test__/user-orgs` - Set user's organizations
+- `/__test__/user-packages` - Set user's packages
+- `/__test__/package` - Set package collaborators
+
 ## Submitting changes
 
 ### Before submitting
@@ -767,8 +892,10 @@ Format: `type(scope): description`
 - `fix(i18n): update French translations`
 - `chore(deps): update vite to v6`
 
+Where front end changes are made, please include before and after screenshots in your pull request description.
+
 > [!NOTE]
-> The subject must start with a lowercase letter. Individual commit messages within your PR don't need to follow this format since they'll be squashed.
+> Use lowercase letters in your pull request title. Individual commit messages within your PR don't need to follow this format since they'll be squashed.
 
 ### PR descriptions
 

CONTRIBUTING.md

@@ -116,7 +116,7 @@ npmx.dev supports npm permalinks – just replace `npmjs.com` with `npmx.dev
 | `npmjs.com/org/nuxt`            | [`npmx.dev/org/nuxt`](https://npmx.dev/org/nuxt)                       |
 
 > [!TIP]
-> Want automatic redirects? Try the [npmx-replace browser extension](https://github.com/tylersayshi/npmx-replace-extension) (Chrome only for now).
+> Want automatic redirects? Try the [npmx-replace browser extension](https://github.com/tylersayshi/npmx-replace-extension) (Chrome only for now) or the separate [npmx-redirect extension](https://github.com/iaverages/npmx-redirect) for [Chrome](https://chromewebstore.google.com/detail/lbhjgfgpnlihfmobnohoipeljollhlnb) / [Firefox](https://addons.mozilla.org/en-GB/firefox/addon/npmx-redirect/).
 
 #### Not yet supported
 
@@ -159,6 +159,7 @@ We welcome contributions – please do feel free to explore the project and
 - [nxjt](https://nxjt.netlify.app) – npmx Jump To: Quickly navigate to npmx common webpages.
 - [npmx-weekly](https://npmx-weekly.trueberryless.org/) – A weekly newsletter for the npmx ecosystem. Add your own content via suggestions in the weekly PR on [GitHub](https://github.com/trueberryless-org/npmx-weekly/pulls?q=is%3Aopen+is%3Apr+label%3A%22%F0%9F%95%94+weekly+post%22).
 - [npmx-digest](https://npmx-digest.trueberryless.org/) – An automated news aggregation website that summarizes npmx activity from GitHub and Bluesky every 8 hours.
+- [npmx-redirect](https://github.com/iaverages/npmx-redirect) – Browser extension that automatically redirects npmjs.com URLs to npmx.dev.
 
 If you're building something cool, let us know! 🙏
 

README.md

@@ -127,7 +127,7 @@ if (import.meta.client) {
 
     <AppHeader :show-logo="!isHomepage" />
 
-    <div id="main-content" class="flex-1 flex flex-col">
+    <div id="main-content" class="flex-1 flex flex-col" tabindex="-1">
       <NuxtPage />
     </div>
 

app/app.vue

@@ -23,6 +23,9 @@ const showModal = () => modalRef.value?.showModal?.()
           <LinkBase :to="{ name: 'privacy' }">
             {{ $t('privacy_policy.title') }}
           </LinkBase>
+          <LinkBase :to="{ name: 'accessibility' }">
+            {{ $t('a11y.footer_title') }}
+          </LinkBase>
           <button
             type="button"
             class="cursor-pointer group inline-flex gap-x-1 items-center justify-center underline-offset-[0.2rem] underline decoration-1 decoration-fg/30 font-mono text-fg hover:(decoration-accent text-accent) focus-visible:(decoration-accent text-accent) transition-colors duration-200"

app/components/AppFooter.vue

@@ -64,6 +64,14 @@ const mobileLinks = computed<NavigationConfigWithGroups>(() => [
         external: false,
         iconClass: 'i-carbon:security',
       },
+      {
+        name: 'Accessibility',
+        label: $t('a11y.title'),
+        to: { name: 'accessibility' },
+        type: 'link',
+        external: false,
+        iconClass: 'i-carbon:accessibility-alt',
+      },
     ],
   },
   {
@@ -172,7 +180,7 @@ onKeyStroke(
     for (const link of desktopLinks.value) {
       if (link.to && link.keyshortcut && isKeyWithoutModifiers(e, link.keyshortcut)) {
         e.preventDefault()
-        navigateTo(link.to.name)
+        navigateTo(link.to)
         break
       }
     }

app/components/AppHeader.vue

@@ -24,6 +24,7 @@ defineProps<{
       font-size="420"
       font-weight="500"
       text-anchor="middle"
+      style="user-select: none"
     >
       <tspan>/</tspan>
     </text>