@nocobase/client-v2 2.2.0-beta.1 → 2.2.0-beta.11

package/src/__tests__/plugin-manager.test.tsx

@@ -18,6 +18,19 @@ class TestAclPlugin extends Plugin {
   }
 }
 
+class TestSettingsLinkPlugin extends Plugin {
+  async load() {
+    this.app.pluginSettingsManager.addMenuItem({ key: 'shared-settings', title: 'Shared settings' });
+    this.app.pluginSettingsManager.addPageTabItem({
+      menuKey: 'shared-settings',
+      key: 'target',
+      title: 'Target settings',
+      Component: () => <div>Target settings page</div>,
+    });
+    this.app.pluginSettingsManager.setPluginSettingsLink('demo-plugin', 'shared-settings.target');
+  }
+}
+
 type MockClientApplication = ReturnType<typeof createMockClient>;
 
 const renderApp = (app: MockClientApplication) => {
@@ -35,9 +48,9 @@ const waitForGetRequests = async (app: MockClientApplication, urls: string[]) =>
   );
 };
 
-const setupApp = (pmList: any[]) => {
+const setupApp = (pmList: any[], plugins: Array<typeof Plugin> = []) => {
   const app = createMockClient({
-    plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
+    plugins: [NocoBaseBuildInPlugin, TestAclPlugin, ...plugins],
     router: { type: 'memory', initialEntries: ['/admin/settings/plugin-manager'] },
   });
 
@@ -174,4 +187,33 @@ describe('plugin-manager page', () => {
       expect(removeCall?.params).toMatchObject({ filterByTk: 'demo-plugin' });
     });
   });
+
+  it('shows Settings for a plugin linked to a different settings page', async () => {
+    const app = setupApp(
+      [
+        {
+          name: 'demo-plugin',
+          packageName: '@nocobase/demo-plugin',
+          displayName: 'Demo plugin',
+          description: 'A demo',
+          enabled: true,
+          builtIn: false,
+          removable: false,
+          version: '0.1.0',
+          isCompatible: true,
+          keywords: [],
+        },
+      ],
+      [TestSettingsLinkPlugin],
+    );
+
+    renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check', 'pm:list']);
+
+    const card = await screen.findByRole('button', { name: 'Demo plugin' });
+    const settingsLink = within(card.closest('.ant-card') as HTMLElement).getByText('Settings');
+    fireEvent.click(settingsLink);
+
+    expect(await screen.findByText('Target settings page')).toBeInTheDocument();
+  });
 });

package/src/__tests__/settings-center.test.tsx

@@ -14,7 +14,7 @@ import { message } from 'antd';
 import { AdminSettingsLayoutModel as ClientV2AdminSettingsLayoutModel } from '../settings-center';
 import { AdminSettingsLayoutModel as ClientV1AdminSettingsLayoutModel } from '../../../client/src/pm/AdminSettingsLayoutModel';
 import { NocoBaseBuildInPlugin } from '../nocobase-buildin-plugin';
-import { matchSettingsRoute } from '../settings-center/utils';
+import { matchSettingsRoute, sortTopLevelSettings } from '../settings-center/utils';
 
 class TestAclPlugin extends Plugin {
   async load() {
@@ -168,6 +168,12 @@ describe('settings center', () => {
     });
   });
 
+  it('should sort system-settings with other top-level settings by normal ordering', () => {
+    const settings = [{ name: 'system-settings' }, { name: 'api-keys' }, { name: 'backups' }] as any;
+
+    expect(sortTopLevelSettings(settings).map((item) => item.name)).toEqual(['api-keys', 'backups', 'system-settings']);
+  });
+
   it('should redirect /admin/settings to system-settings by default', async () => {
     const app = createMockClient({
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin],
@@ -354,6 +360,39 @@ describe('settings center', () => {
     expect(screen.getByRole('menuitem', { name: 'Menu ACL Demo' })).toBeInTheDocument();
   });
 
+  it('should allow the settings sidebar menu to scroll independently', async () => {
+    class ManySettingsPlugin extends Plugin {
+      async load() {
+        for (let index = 0; index < 30; index += 1) {
+          this.pluginSettingsManager.addMenuItem({
+            key: `scroll-demo-${index}`,
+            title: `Scroll demo ${index}`,
+          });
+          this.pluginSettingsManager.addPageTabItem({
+            menuKey: `scroll-demo-${index}`,
+            key: 'index',
+            title: `Scroll demo ${index}`,
+            Component: () => <div>{`Scroll demo page ${index}`}</div>,
+          });
+        }
+      }
+    }
+
+    const app = createMockClient({
+      plugins: [NocoBaseBuildInPlugin, TestAclPlugin, ManySettingsPlugin],
+      router: { type: 'memory', initialEntries: ['/admin/settings/scroll-demo-29'] },
+    });
+    mockAdminRuntime(app);
+
+    await renderApp(app);
+    await waitForGetRequests(app, ['/auth:check', 'roles:check']);
+
+    expect(await screen.findByText('Scroll demo page 29')).toBeInTheDocument();
+
+    const sidebar = screen.getByRole('menuitem', { name: 'Scroll demo 29' }).closest('.ant-layout-sider');
+    expect(sidebar).toHaveStyle({ overflowY: 'auto' });
+  });
+
   it('should save system settings through systemSettings:put', async () => {
     const app = createMockClient({
       plugins: [NocoBaseBuildInPlugin, TestAclPlugin],

package/src/authRedirect.ts

@@ -204,6 +204,44 @@ function getDefaultV2AdminRedirectPath(app: AppLike) {
   return joinRootRelativePath(getV2EffectiveBasePath(app), '/admin');
 }
 
+function isSafeRootRelativePath(value?: string | null) {
+  return !!value && value.startsWith('/') && !value.startsWith('//') && !value.startsWith('/\\');
+}
+
+function preserveTrailingSlash(originalPathname: string, value: string) {
+  if (originalPathname !== '/' && originalPathname.endsWith('/') && !value.endsWith('/')) {
+    return `${value}/`;
+  }
+  return value;
+}
+
+export function normalizeV2RedirectPath(app: AppLike, target?: string | null, fallbackPath = '/admin/') {
+  // In a v2 sub-app, publicPath can be `/v/` while the active router
+  // basename is `/v/apps/a/`. Redirects must resolve under the basename.
+  const basePath = trimTrailingSlashes(getV2EffectiveBasePath(app)) || '/';
+  const fallbackTarget = isSafeRootRelativePath(fallbackPath) ? fallbackPath : '/admin/';
+  const rawTarget = isSafeRootRelativePath(target) ? target : fallbackTarget;
+  let { pathname, search, hash } = splitPathLike(rawTarget);
+  let normalizedPathname = normalizePathname(pathname);
+
+  // Already under the current v2 runtime, e.g. `/v/apps/a/admin/`.
+  if (basePath === '/' || normalizedPathname === basePath || normalizedPathname.startsWith(`${basePath}/`)) {
+    return `${preserveTrailingSlash(pathname, normalizedPathname)}${normalizeSearch(search)}${normalizeHash(hash)}`;
+  }
+
+  const publicPath = trimTrailingSlashes(getV2PublicPath(app)) || '/';
+  // Under v2 publicPath but outside the current basename, e.g. `/v/admin/`
+  // inside `/v/apps/a/`; use fallback so it lands on `/v/apps/a/admin/`.
+  if (publicPath !== '/' && (normalizedPathname === publicPath || normalizedPathname.startsWith(`${publicPath}/`))) {
+    ({ pathname, search, hash } = splitPathLike(fallbackTarget));
+    normalizedPathname = normalizePathname(pathname);
+  }
+
+  // Basename-relative target, e.g. `/admin/`, becomes `/v/apps/a/admin/`.
+  const joinedPathname = preserveTrailingSlash(pathname, joinRootRelativePath(basePath, normalizedPathname));
+  return `${joinedPathname}${normalizeSearch(search)}${normalizeHash(hash)}`;
+}
+
 /**
  * 将当前 v2 页面地址转换为根相对 redirect 路径。
  *

package/src/collection-field-interface/CollectionFieldInterface.ts

@@ -115,6 +115,7 @@ export abstract class CollectionFieldInterface {
   titleUsable?: boolean;
   usePathOptions?(field: any): any;
   hidden?: boolean;
+  creatable?: boolean;
 
   addComponentOption(componentOption: CollectionFieldInterfaceComponentOption) {
     if (!this.componentOptions) {

package/src/collection-field-interface/CollectionFieldInterfaceManager.ts

@@ -31,6 +31,7 @@ interface FieldInterfaceLike {
   title?: ReactNode;
   group?: string;
   order?: number;
+  creatable?: boolean;
   isAssociation?: boolean;
   supportDataSourceType?: string[];
   notSupportDataSourceType?: string[];

package/src/collection-manager/field-configure.ts

@@ -530,7 +530,7 @@ export function reverseFieldConfigureItems(): FieldConfigureItem[] {
       component: 'Input',
       required: true,
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
       hidden: ({ context, values }) => !context.showReverseFieldConfig && !get(values, 'autoCreateReverseField'),
       disabled: ({ context }) => !context.showReverseFieldConfig,
     },

package/src/collection-manager/interfaces/id.ts

@@ -48,7 +48,7 @@ export class IdFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
   };
   filterable = {

package/src/collection-manager/interfaces/m2m.tsx

@@ -158,7 +158,7 @@ export class M2MFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',
@@ -192,7 +192,7 @@ export class M2MFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/m2o.tsx

@@ -69,7 +69,7 @@ export class M2OFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -123,7 +123,7 @@ export class M2OFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/nanoid.ts

@@ -42,7 +42,7 @@ export class NanoidFieldInterface extends CollectionFieldInterface {
       'x-component': 'Input',
       'x-disabled': '{{ !createOnly }}',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     customAlphabet: {
       type: 'string',

package/src/collection-manager/interfaces/o2m.tsx

@@ -68,7 +68,7 @@ export class O2MFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -135,7 +135,7 @@ export class O2MFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/obo.tsx

@@ -55,7 +55,7 @@ export class OBOFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -109,7 +109,7 @@ export class OBOFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/oho.tsx

@@ -55,7 +55,7 @@ export class OHOFieldInterface extends CollectionFieldInterface {
       'x-decorator': 'FormItem',
       'x-component': 'Input',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     type: relationshipType,
     grid: {
@@ -123,7 +123,7 @@ export class OHOFieldInterface extends CollectionFieldInterface {
                   required: true,
                   default: '{{ useNewId("f_") }}',
                   description:
-                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+                    "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
                   'x-decorator': 'FormItem',
                   'x-component': 'ForeignKey',
                   'x-validator': 'uid',

package/src/collection-manager/interfaces/properties/index.ts

@@ -141,7 +141,7 @@ export const reverseFieldProperties: Record<string, ISchema> = {
         'x-validator': 'uid',
         'x-disabled': '{{ !showReverseFieldConfig }}',
         description:
-          "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+          "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
       },
     },
   },
@@ -399,7 +399,7 @@ export const defaultProps = {
     'x-component': 'Input',
     'x-validator': 'uid',
     description:
-      "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+      "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
   },
 };
 

package/src/collection-manager/interfaces/uuid.ts

@@ -46,7 +46,7 @@ export class UUIDFieldInterface extends CollectionFieldInterface {
       'x-component': 'Input',
       'x-disabled': '{{ !createOnly }}',
       description:
-        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with an letter.')}}",
+        "{{t('Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.')}}",
     },
     autoFill,
     layout: {

package/src/components/AppComponents.tsx

@@ -21,7 +21,13 @@ import type { Application } from '../Application';
 interface AppErrorPayload {
   code?: string;
   message?: string;
-  command?: { name: string };
+  command?: {
+    name: string;
+    components?: {
+      maintaining?: string;
+      maintainingDialog?: string;
+    };
+  };
   [key: string]: any;
 }
 
@@ -188,7 +194,12 @@ export const AppError: FC<{ error: Error & { title?: string }; app: Application
 );
 
 export const AppMaintaining: FC<{ app: Application; error: Error }> = observer(
-  ({ app }) => {
+  ({ app, error }) => {
+    const component = (error as AppErrorPayload | undefined)?.command?.components?.maintaining;
+    if (component) {
+      return app.renderComponent(component, { app, error });
+    }
+
     const { icon, status, title, subTitle } = getProps(app);
     return (
       <div>
@@ -211,7 +222,12 @@ export const AppMaintaining: FC<{ app: Application; error: Error }> = observer(
 );
 
 export const AppMaintainingDialog: FC<{ app: Application; error: Error }> = observer(
-  ({ app }) => {
+  ({ app, error }) => {
+    const component = (error as AppErrorPayload | undefined)?.command?.components?.maintainingDialog;
+    if (component) {
+      return app.renderComponent(component, { app, error });
+    }
+
     const { icon, status, title, subTitle } = getProps(app);
     return (
       <Modal open={true} footer={null} closable={false}>

package/src/components/form/JsonTextArea.tsx

@@ -10,8 +10,9 @@
 import { css, cx } from '@emotion/css';
 import { Input, Typography } from 'antd';
 import type { TextAreaProps } from 'antd/es/input';
+import type { TextAreaRef } from 'antd/es/input/TextArea';
 import JSON5 from 'json5';
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState, type ChangeEvent, type FocusEvent } from 'react';
 
 export interface JsonTextAreaProps extends Omit<TextAreaProps, 'value' | 'onChange'> {
   value?: unknown;
@@ -36,14 +37,14 @@ function stringifyJsonValue(value: unknown, json: typeof JSON | typeof JSON5, sp
       json.parse(value);
       return value;
     } catch {
-      return json.stringify(value, undefined, space);
+      return json.stringify(value, undefined, space) ?? '';
     }
   }
 
-  return json.stringify(value, undefined, space);
+  return json.stringify(value, undefined, space) ?? '';
 }
 
-export const JsonTextArea = React.memo((props: JsonTextAreaProps) => {
+const JsonTextAreaComponent = React.forwardRef<TextAreaRef, JsonTextAreaProps>((props, ref) => {
   const {
     value,
     onChange,
@@ -74,11 +75,8 @@ export const JsonTextArea = React.memo((props: JsonTextAreaProps) => {
     [json],
   );
 
-  const handleChange = useCallback(
-    (event: React.ChangeEvent<HTMLTextAreaElement>) => {
-      const nextText = event.target.value;
-      setText(nextText);
-
+  const validateText = useCallback(
+    (nextText: string) => {
       try {
         parseText(nextText);
         setError(undefined);
@@ -89,12 +87,21 @@ export const JsonTextArea = React.memo((props: JsonTextAreaProps) => {
     [parseText],
   );
 
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => {
+      const nextText = event.target.value;
+      setText(nextText);
+      validateText(nextText);
+    },
+    [validateText],
+  );
+
   const handleBlur = useCallback(
-    (event: React.FocusEvent<HTMLTextAreaElement>) => {
+    (event: FocusEvent<HTMLTextAreaElement>) => {
       try {
         const parsed = parseText(event.target.value);
         setError(undefined);
-        setText(parsed == null ? '' : json.stringify(parsed, undefined, space));
+        setText(parsed == null ? '' : json.stringify(parsed, undefined, space) ?? '');
         onChange?.(parsed);
       } catch (err) {
         setError(err instanceof Error ? err.message : String(err));
@@ -111,6 +118,7 @@ export const JsonTextArea = React.memo((props: JsonTextAreaProps) => {
     <>
       <Input.TextArea
         {...textAreaProps}
+        ref={ref}
         value={text}
         onChange={handleChange}
         onBlur={handleBlur}
@@ -126,4 +134,6 @@ export const JsonTextArea = React.memo((props: JsonTextAreaProps) => {
   );
 });
 
+export const JsonTextArea = React.memo(JsonTextAreaComponent);
+
 JsonTextArea.displayName = 'JsonTextArea';

package/src/components/form/ScanInput/__tests__/useCodeScanner.test.tsx

@@ -7,9 +7,9 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { render, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import React, { useCallback } from 'react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { DEFAULT_CODE_FORMATS, getCodeScanBoxSize, useCodeScanner } from '../useCodeScanner';
 
 type MockScannerInstance = {
@@ -44,6 +44,12 @@ const mocks = vi.hoisted(() => {
   };
 });
 
+const jsQrMocks = vi.hoisted(() => {
+  return {
+    default: vi.fn(),
+  };
+});
+
 vi.mock('html5-qrcode', () => ({
   Html5Qrcode: mocks.Html5Qrcode,
   Html5QrcodeScannerState: {
@@ -66,6 +72,8 @@ vi.mock('html5-qrcode', () => ({
   },
 }));
 
+vi.mock('jsqr', () => jsQrMocks);
+
 function ScannerHost({ scanBoxSize }: { scanBoxSize?: { width: number; height: number } } = {}) {
   const handleScanSuccess = useCallback(() => undefined, []);
 
@@ -79,9 +87,74 @@ function ScannerHost({ scanBoxSize }: { scanBoxSize?: { width: number; height: n
   return <div id="scanner" />;
 }
 
+function FileScannerHost({ onScanSuccess }: { onScanSuccess: (text: string) => void }) {
+  const { startScanFile } = useCodeScanner({
+    elementId: 'scanner',
+    enabled: true,
+    onScanSuccess,
+  });
+
+  return (
+    <>
+      <div id="scanner" />
+      <button onClick={() => startScanFile(new File(['qr'], 'qr.png', { type: 'image/png' }))}>scan file</button>
+    </>
+  );
+}
+
+function stubSafariBrowser() {
+  vi.spyOn(window.navigator, 'vendor', 'get').mockReturnValue('Apple Computer, Inc.');
+  vi.spyOn(window.navigator, 'userAgent', 'get').mockReturnValue(
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15',
+  );
+}
+
+function stubImageElement(size: { width: number; height: number } = { width: 600, height: 400 }) {
+  vi.stubGlobal(
+    'Image',
+    class MockImage {
+      onabort: ((event: Event) => void) | null = null;
+      onerror: ((event: Event) => void) | null = null;
+      onload: (() => void) | null = null;
+      height = size.height;
+      naturalHeight = size.height;
+      naturalWidth = size.width;
+      width = size.width;
+
+      set src(_value: string) {
+        this.onload?.();
+      }
+    },
+  );
+  vi.stubGlobal('URL', {
+    ...URL,
+    createObjectURL: vi.fn(() => 'blob:qr'),
+    revokeObjectURL: vi.fn(),
+  });
+}
+
+function stubCanvas() {
+  const canvasContext = {
+    drawImage: vi.fn(),
+    getImageData: vi.fn((_x: number, _y: number, width: number, height: number) => ({
+      data: new Uint8ClampedArray(width * height * 4),
+      height,
+      width,
+    })),
+  } as unknown as CanvasRenderingContext2D;
+
+  vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(canvasContext);
+}
+
 describe('useCodeScanner', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    jsQrMocks.default.mockReturnValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
   });
 
   it('starts scanning with QR code and barcode formats by default', async () => {
@@ -120,4 +193,74 @@ describe('useCodeScanner', () => {
 
     expect(config?.qrbox?.(1200, 844)).toEqual({ width: 319, height: 240 });
   });
+
+  it('uses jsQR first for Safari uploaded QR images', async () => {
+    const handleScanSuccess = vi.fn();
+    jsQrMocks.default.mockReturnValueOnce({ data: 'JSQR-CODE' });
+    stubSafariBrowser();
+    stubImageElement();
+    stubCanvas();
+
+    render(<FileScannerHost onScanSuccess={handleScanSuccess} />);
+    await waitFor(() => expect(mocks.start).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByText('scan file'));
+
+    await waitFor(() => expect(handleScanSuccess).toHaveBeenCalledWith('JSQR-CODE'));
+    expect(jsQrMocks.default).toHaveBeenCalledWith(expect.any(Uint8ClampedArray), 600, 400, {
+      inversionAttempts: 'attemptBoth',
+    });
+    expect(mocks.scanFileV2).not.toHaveBeenCalled();
+  });
+
+  it('falls back to html5-qrcode for Safari uploaded files when jsQR does not decode a QR code', async () => {
+    const handleScanSuccess = vi.fn();
+    mocks.scanFileV2.mockResolvedValueOnce({ decodedText: 'BARCODE-CODE' });
+    stubSafariBrowser();
+    stubImageElement();
+    stubCanvas();
+
+    render(<FileScannerHost onScanSuccess={handleScanSuccess} />);
+    await waitFor(() => expect(mocks.start).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByText('scan file'));
+
+    await waitFor(() => expect(handleScanSuccess).toHaveBeenCalledWith('BARCODE-CODE'));
+    expect(jsQrMocks.default).toHaveBeenCalled();
+    expect(mocks.scanFileV2).toHaveBeenCalled();
+  });
+
+  it('tries multiple image scales before falling back from Safari jsQR scanning', async () => {
+    const handleScanSuccess = vi.fn();
+    Array.from({ length: 8 }).forEach((_, index) => {
+      jsQrMocks.default.mockReturnValueOnce(index === 7 ? { data: 'SCALED-CODE' } : undefined);
+    });
+    stubSafariBrowser();
+    stubImageElement({ width: 4000, height: 3000 });
+    stubCanvas();
+
+    render(<FileScannerHost onScanSuccess={handleScanSuccess} />);
+    await waitFor(() => expect(mocks.start).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByText('scan file'));
+
+    await waitFor(() => expect(handleScanSuccess).toHaveBeenCalledWith('SCALED-CODE'));
+    expect(jsQrMocks.default).toHaveBeenCalledTimes(8);
+  });
+
+  it('tries enhanced grayscale QR images for blurry Safari uploads', async () => {
+    const handleScanSuccess = vi.fn();
+    jsQrMocks.default.mockReturnValueOnce(undefined).mockReturnValueOnce({ data: 'ENHANCED-CODE' });
+    stubSafariBrowser();
+    stubImageElement();
+    stubCanvas();
+
+    render(<FileScannerHost onScanSuccess={handleScanSuccess} />);
+    await waitFor(() => expect(mocks.start).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByText('scan file'));
+
+    await waitFor(() => expect(handleScanSuccess).toHaveBeenCalledWith('ENHANCED-CODE'));
+    expect(jsQrMocks.default).toHaveBeenCalledTimes(2);
+  });
 });