@shipfox/client-shell 1.0.0 → 3.0.1

package/test/external/FINDINGS.md

@@ -1,41 +0,0 @@
-# External composition findings
-
-The graduated fixture uses the production `@shipfox/client-features` default composition and the
-complete recursive client runtime closure from `publication-closure.json`. The external feature is
-application-local, so route implementations and generated types cross the same package boundary as
-a downstream distribution.
-
-## Contract proof
-
-The fixture proves that:
-
-- every default feature contributes its production routes to the generated application module;
-- an application-local settings route is added and the default login route is explicitly replaced;
-- two application-local providers receive the shell query client and Jotai store, then nest in
-  declaration order;
-- application navigation and settings data render through the shell-owned registries;
-- the external config fragment is required, merged, and readable by both providers and the route;
-- the generated router types an application-local `Link` and `useParams` call; and
-- the unapproved login collision fails with the exact normative diagnostic.
-
-## Distribution isolation
-
-Packed mode builds declarations and runtime files before creating tarballs, then productionizes a
-temporary copy of each package manifest like `release:publish` so source conditions cannot leak into
-the consumer artifact or mutate the worktree. The fixture declares only the documented client
-composition roots, plus `@shipfox/client-config` for its own config proof, while `file:` overrides
-keep every first-party runtime dependency in the full closure on its local tarball. It rejects
-registry-resolved Shipfox packages and `workspace:` ranges across every installed closure package,
-checks that generated package imports are direct fixture dependencies, and confirms full-closure
-runtime imports resolve through `dist` under default and `development` conditions while TypeScript
-checks every packed declaration graph. Linked mode keeps the
-minimal-consumer, generated-route, behavior, collision, and type checks for faster local iteration;
-its workspace packages intentionally resolve `development` to source.
-
-## Collision diagnostic
-
-The rejected build must return this diagnostic and a non-zero status:
-
-```text
-Route "/auth/login" is contributed by both features "shipfox.auth" and "fixture.unapproved-collision". Set override: true to replace it explicitly.
-```

package/test/external/README.md

@@ -1,37 +0,0 @@
-# External client runtime fixture
-
-This fixture packs the published client runtime closure into a Vite application outside the pnpm
-workspace. The application starts from `defaultFeatures()` and adds one external feature that
-replaces the login route, adds a settings route, appends providers, contributes navigation and
-settings entries, and merges a config fragment.
-
-## Run the required packed gate
-
-The package script builds runtime files and declarations from a clean checkout before packing the
-full client closure:
-
-```sh
-pnpm --filter=@shipfox/client-shell test:external
-```
-
-The gate installs only the nine documented client composition roots, plus
-`@shipfox/client-config` used by the fixture's own config proof, as direct dependencies. It uses
-release-shaped local tarballs and overrides for the full `@shipfox/*` runtime closure. It verifies
-that generated package imports are declared direct dependencies, checks default and `development`
-condition resolution through `dist`, type-checks every packed declaration graph, generates the
-composed TanStack router, builds and type-checks the consumer, runs the behavioral fixture, and
-asserts the exact rejected-collision diagnostic. CI runs this command during static verification.
-
-## Run the linked iteration mode
-
-```sh
-pnpm --filter=@shipfox/client-shell test:external -- --link
-```
-
-This copies the Vite template to a temporary directory and links the workspace-built closure. It
-runs the same minimal-consumer, generated-route, behavior, collision, and type assertions without
-packing tarballs. The packed-only `development` check is omitted because linked workspace packages
-intentionally resolve that condition to source.
-
-Both modes remove their temporary directories after completion. The behavioral composition fixture
-uses Vitest with JSDOM and does not need browser E2E infrastructure.

package/test/external/fixture/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Shipfox client composition fixture</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

package/test/external/fixture/package.json

@@ -1,31 +0,0 @@
-{
-  "name": "shipfox-client-shell-external-fixture",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "type": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@tanstack/react-query": "5.101.0",
-    "@tanstack/react-router": "1.170.16",
-    "@tanstack/router-core": "1.171.13",
-    "jotai": "2.20.1",
-    "react": "19.2.7",
-    "react-dom": "19.2.7",
-    "zod": "4.4.3"
-  },
-  "devDependencies": {
-    "@storybook/react": "10.4.6",
-    "@types/node": "24.13.2",
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "6.0.2",
-    "jsdom": "29.1.1",
-    "typescript": "6.0.3",
-    "vite": "8.0.16",
-    "vitest": "4.1.9"
-  }
-}

package/test/external/fixture/src/app.fixture.tsx

@@ -1,104 +0,0 @@
-import {getLoadedConfig} from '@shipfox/client-config';
-import {QueryClient} from '@tanstack/react-query';
-import {createMemoryHistory} from '@tanstack/react-router';
-import {flushSync} from 'react-dom';
-import {createRoot, type Root} from 'react-dom/client';
-import {auth, ClientApp, workspaceSetup} from './main';
-import {readProviderEvidence, resetProviderEvidence} from './provider';
-import {router} from './shipfox-app.gen';
-
-let container: HTMLDivElement;
-let root: Root;
-
-beforeEach(() => {
-  window.matchMedia = vi.fn((query: string) => ({
-    matches: false,
-    media: query,
-    onchange: null,
-    addListener: vi.fn(),
-    removeListener: vi.fn(),
-    addEventListener: vi.fn(),
-    removeEventListener: vi.fn(),
-    dispatchEvent: vi.fn(() => false),
-  }));
-  window.scrollTo = vi.fn();
-  resetProviderEvidence();
-  container = document.createElement('div');
-  document.body.append(container);
-  root = createRoot(container);
-});
-
-afterEach(() => {
-  flushSync(() => root.unmount());
-  container.remove();
-});
-
-function mountClient(): void {
-  flushSync(() => root.render(<ClientApp />));
-}
-
-function heading(name: string): Element | undefined {
-  return [...container.querySelectorAll('h1, h2, h3')].find(
-    (element) => element.textContent?.trim() === name,
-  );
-}
-
-test('reports a missing external config fragment', async () => {
-  window.__SHIPFOX_CONFIG__ = undefined;
-
-  mountClient();
-
-  await vi.waitFor(() => expect(heading('Configuration error')).toBeDefined());
-  expect(container.textContent).toContain('externalGreeting');
-});
-
-test('renders the explicit default-route replacement', async () => {
-  window.__SHIPFOX_CONFIG__ = {EXTERNAL_GREETING: 'Hello from the external fixture'};
-  router.update({
-    history: createMemoryHistory({initialEntries: ['/auth/login']}),
-    context: {auth: undefined, queryClient: undefined},
-  });
-  await router.load();
-
-  mountClient();
-
-  await vi.waitFor(() => expect(heading('External login')).toBeDefined());
-  expect(heading('Log in')).toBeUndefined();
-});
-
-test('renders the external route, provider order, navigation, settings, and config', async () => {
-  window.__SHIPFOX_CONFIG__ = {EXTERNAL_GREETING: 'Hello from the external fixture'};
-  router.update({
-    history: createMemoryHistory({
-      initialEntries: ['/workspaces/workspace/settings/external'],
-    }),
-    context: {auth, queryClient: new QueryClient(), workspaceSetup},
-  });
-  await router.load();
-  mountClient();
-
-  await vi.waitFor(() => expect(heading('External settings')).toBeDefined());
-  expect(
-    [...container.querySelectorAll('[role="tab"]')].map((tab) => tab.textContent?.trim()),
-  ).toEqual(['Projects', 'External', 'Settings']);
-  expect(
-    [...container.querySelectorAll('[aria-label="Workspace settings"] a')]
-      .map((link) => link.textContent?.trim())
-      .slice(0, 3),
-  ).toEqual(['Members', 'External', 'Runners']);
-  expect(container.querySelector('[aria-label="External provider order"]')?.textContent).toBe(
-    'outer > inner',
-  );
-  expect(container.textContent).toContain('Hello from the external fixture');
-  await vi.waitFor(() => expect(readProviderEvidence().map(({id}) => id)).toEqual(['outer', 'inner']));
-  const providers = readProviderEvidence();
-  expect(providers[1]?.queryClient).toBe(providers[0]?.queryClient);
-  expect(providers[1]?.store).toBe(providers[0]?.store);
-  expect(providers.map(({externalGreeting}) => externalGreeting)).toEqual([
-    'Hello from the external fixture',
-    'Hello from the external fixture',
-  ]);
-  expect(getLoadedConfig<{externalGreeting: string}>().externalGreeting).toBe(
-    'Hello from the external fixture',
-  );
-});

package/test/external/fixture/src/features/external-settings.tsx

@@ -1,19 +0,0 @@
-import {getLoadedConfig} from '@shipfox/client-config';
-import {defineRoute} from '@shipfox/client-shell/runtime';
-import {useProviderOrder} from '../provider';
-
-function ExternalSettings() {
-  const providerOrder = useProviderOrder();
-  const config = getLoadedConfig<{externalGreeting: string}>();
-  return (
-    <section>
-      <h1>External settings</h1>
-      <p>{config.externalGreeting}</p>
-      <output aria-label="External provider order">{providerOrder.join(' > ')}</output>
-    </section>
-  );
-}
-
-const route = defineRoute({component: ExternalSettings});
-
-export default route;

package/test/external/fixture/src/features/login-override.tsx

@@ -1,9 +0,0 @@
-import {defineRoute} from '@shipfox/client-shell/runtime';
-
-function ExternalLogin() {
-  return <h1>External login</h1>;
-}
-
-const route = defineRoute({component: ExternalLogin});
-
-export default route;

package/test/external/fixture/src/features.collision.ts

@@ -1,15 +0,0 @@
-import {defaultFeatures} from '@shipfox/client-features';
-import {defineClientFeature} from '@shipfox/client-shell';
-
-const collisionFeature = defineClientFeature({
-  id: 'fixture.unapproved-collision',
-  routes: [
-    {
-      path: '/auth/login',
-      parent: 'root',
-      impl: './features/login-override',
-    },
-  ],
-});
-
-export const features = [...defaultFeatures(), collisionFeature];

package/test/external/fixture/src/features.ts

@@ -1,50 +0,0 @@
-import {defaultFeatures} from '@shipfox/client-features';
-import {defineClientFeature} from '@shipfox/client-shell';
-import {z} from 'zod';
-import {ExternalProviderInner, ExternalProviderOuter} from './provider';
-
-export const externalConfigShape = {
-  externalGreeting: z.string(),
-};
-
-export const externalFeature = defineClientFeature({
-  id: 'fixture.external',
-  routes: [
-    {
-      path: '/auth/login',
-      parent: 'root',
-      override: true,
-      impl: './features/login-override',
-    },
-    {
-      path: '/workspaces/$wid/settings/external',
-      parent: 'workspaceSettings',
-      impl: './features/external-settings',
-    },
-  ],
-  providers: [
-    {id: 'fixture-provider-outer', Component: ExternalProviderOuter},
-    {id: 'fixture-provider-inner', Component: ExternalProviderInner},
-  ],
-  navigation: [
-    {
-      id: 'nav.external',
-      scope: 'workspace',
-      label: 'External',
-      to: '/workspaces/$wid/settings/external',
-      order: 150,
-    },
-  ],
-  settingsSections: [
-    {
-      id: 'settings.external',
-      pathSegment: 'external',
-      label: 'External',
-      icon: 'settings3Line',
-      order: 150,
-    },
-  ],
-  configShape: externalConfigShape,
-});
-
-export const features = [...defaultFeatures(), externalFeature];

package/test/external/fixture/src/link-typecheck.tsx

@@ -1,10 +0,0 @@
-import {Link, useParams} from '@tanstack/react-router';
-
-export function ExternalSettingsLink() {
-  const params = useParams({from: '/workspaces/$wid/settings/external'});
-  return (
-    <Link to="/workspaces/$wid/settings/external" params={{wid: params.wid}}>
-      External settings
-    </Link>
-  );
-}

package/test/external/fixture/src/main.tsx

@@ -1,86 +0,0 @@
-import {
-  ConfigErrorScreen,
-  getWindowRuntimeConfig,
-  loadConfig,
-  setLoadedConfig,
-} from '@shipfox/client-config';
-import {
-  authStateAtom,
-  ChromeProvider,
-  type AuthState,
-  type AuthStateValue,
-  mergeConfigShapes,
-  type RouterContext,
-} from '@shipfox/client-shell/runtime';
-import {ShellProviders} from '@shipfox/client-shell/testing';
-import {QueryClient} from '@tanstack/react-query';
-import {Outlet, RouterProvider} from '@tanstack/react-router';
-import {createStore} from 'jotai';
-import {useState} from 'react';
-import {createRoot} from 'react-dom/client';
-import {features} from './features';
-import {router} from './shipfox-app.gen';
-
-const authState: AuthState = {
-  status: 'authenticated',
-  workspaces: [{id: 'workspace', name: 'External workspace', membershipId: 'membership'}],
-};
-
-export const auth: AuthStateValue = {
-  ...authState,
-  isLoading: false,
-  isAuthenticated: true,
-  hasWorkspace: true,
-  workspaces: authState.workspaces ?? [],
-};
-
-export const workspaceSetup: NonNullable<RouterContext['workspaceSetup']> = async () => ({
-  hideProjectNavigation: false,
-});
-
-function FixtureProjectBreadcrumb() {
-  return null;
-}
-
-function FixtureProjectLayoutGuard() {
-  return <Outlet />;
-}
-
-export function ClientApp() {
-  const [queryClient] = useState(
-    () => new QueryClient({defaultOptions: {queries: {retry: false}}}),
-  );
-  const [store] = useState(() => {
-    const value = createStore();
-    // Linked mode has two Jotai type paths; Vite dedupes them to this store at runtime.
-    value.set(authStateAtom as never, authState);
-    return value;
-  });
-  const config = loadConfig(mergeConfigShapes(features), {
-    runtime: getWindowRuntimeConfig(),
-    build: import.meta.env,
-  });
-  if (!config.ok) return <ConfigErrorScreen errors={config.errors} />;
-  setLoadedConfig(config.config);
-
-  return (
-    <ChromeProvider
-      chrome={{
-        ProjectBreadcrumb: FixtureProjectBreadcrumb,
-        ProjectLayoutGuard: FixtureProjectLayoutGuard,
-      }}
-    >
-      <ShellProviders
-        features={features}
-        queryClient={queryClient}
-        store={store}
-        config={config.config}
-      >
-        <RouterProvider router={router} context={{auth, queryClient, workspaceSetup}} />
-      </ShellProviders>
-    </ChromeProvider>
-  );
-}
-
-const root = document.getElementById('root');
-if (root) createRoot(root).render(<ClientApp />);

package/test/external/fixture/src/provider.ts

@@ -1,45 +0,0 @@
-import {getLoadedConfig} from '@shipfox/client-config';
-import {type QueryClient, useQueryClient} from '@tanstack/react-query';
-import {type createStore, useStore} from 'jotai';
-import {createContext, createElement, type PropsWithChildren, useContext} from 'react';
-
-type Store = ReturnType<typeof createStore>;
-
-export interface ProviderEvidence {
-  id: string;
-  queryClient: QueryClient;
-  store: Store;
-  externalGreeting: string;
-}
-
-const ProviderOrderContext = createContext<readonly string[]>([]);
-const providerEvidence = new Map<string, ProviderEvidence>();
-
-function ExternalProvider({id, children}: PropsWithChildren<{id: string}>) {
-  const parentOrder = useContext(ProviderOrderContext);
-  const queryClient = useQueryClient();
-  const store = useStore();
-  const {externalGreeting} = getLoadedConfig<{externalGreeting: string}>();
-  providerEvidence.set(id, {id, queryClient, store, externalGreeting});
-  return createElement(ProviderOrderContext.Provider, {value: [...parentOrder, id]}, children);
-}
-
-export function ExternalProviderOuter({children}: PropsWithChildren) {
-  return createElement(ExternalProvider, {id: 'outer'}, children);
-}
-
-export function ExternalProviderInner({children}: PropsWithChildren) {
-  return createElement(ExternalProvider, {id: 'inner'}, children);
-}
-
-export function useProviderOrder(): readonly string[] {
-  return useContext(ProviderOrderContext);
-}
-
-export function readProviderEvidence(): readonly ProviderEvidence[] {
-  return [...providerEvidence.values()];
-}
-
-export function resetProviderEvidence(): void {
-  providerEvidence.clear();
-}

package/test/external/fixture/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "strict": true,
-    "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "jsx": "react-jsx",
-    "skipLibCheck": true,
-    "verbatimModuleSyntax": true,
-    "noEmit": true,
-    "types": ["node", "vite/client", "vitest/globals"]
-  },
-  "include": ["src/**/*.ts", "src/**/*.tsx", "types.ts"]
-}

package/test/external/fixture/vite.config.ts

@@ -1,21 +0,0 @@
-import {shipfoxClientComposition} from '@shipfox/client-shell/vite';
-import react from '@vitejs/plugin-react';
-import {defineConfig} from 'vite';
-
-const config = defineConfig({
-  build: {chunkSizeWarningLimit: 4_000},
-  plugins: [
-    shipfoxClientComposition({
-      features:
-        process.env.SHIPFOX_COMPOSITION_COLLISION === '1'
-          ? './src/features.collision.ts'
-          : './src/features.ts',
-    }),
-    react(),
-  ],
-  resolve: {
-    dedupe: ['react', 'react-dom', '@tanstack/react-query', '@tanstack/react-router', 'jotai'],
-  },
-});
-
-export default config;

package/test/external/fixture/vitest.config.ts

@@ -1,17 +0,0 @@
-import react from '@vitejs/plugin-react';
-import {defineConfig} from 'vitest/config';
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    conditions: ['default'],
-    dedupe: ['react', 'react-dom', '@tanstack/react-query', '@tanstack/react-router', 'jotai'],
-  },
-  ssr: {resolve: {conditions: ['default']}},
-  test: {
-    environment: 'jsdom',
-    globals: true,
-    include: ['src/app.fixture.tsx'],
-    server: {deps: {inline: [/@shipfox/, /@radix-ui/, /framer-motion/]}},
-  },
-});