chore(release): bump 4.1.1 — fix root exports, fallback handling, and release docs

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## 4.1.1 (2026-02-17)
+
+### 🐛 Fixed
+
+- **Root export parity**: Re-exported `withRetry`, `redactToken`, rate-limit helpers, and runtime validation guards from the package root so documented imports from `@figma-vars/hooks` work as expected.
+- **Fallback key edge case**: Updated variables hooks and invalidation logic to only treat fallback mode as active when `parsedFallbackFile` is valid, preventing invalid fallback strings from forcing fallback SWR keys.
+- **Test coverage**: Added regression coverage for invalid fallback + live credentials and expanded index export checks for newly documented utilities.
+
 ## 4.0.0 (2025-12-29)
 
 ### ⚠️ BREAKING CHANGES

README.md

@@ -29,6 +29,8 @@ Built for the modern web, this library provides a suite of hooks to fetch, manag
 
 > ⚠️ **Breaking Change**: `useFigmaToken` is now a named export. See [Migration Guide](#-migration-guide-3x--40).
 
+> ✅ **4.1.1 patch**: Fixed root utility exports and fallback key handling when fallback JSON is invalid.
+
 ## 🚀 Features at a Glance
 
 - **Modern React 19.2 hooks** for variables, collections, modes, and published variables
@@ -302,7 +304,7 @@ if (isLocalVariablesResponse(data)) {
 
 ### Error Utilities
 
-v3 introduces powerful error handling utilities for type-safe error checking:
+The library includes powerful error handling utilities for type-safe error checking:
 
 ```tsx
 import { isFigmaApiError, getErrorStatus, getErrorMessage, hasErrorStatus } from '@figma-vars/hooks'
@@ -531,12 +533,21 @@ export function Providers({ children }: { children: React.ReactNode }) {
 - `pnpm run build`, `pnpm test`, `pnpm run test:coverage`
 - `pnpm run check:publint`, `pnpm run check:attw`, `pnpm run check:size`
 
-## 🧭 Release Checklist (for 4.0.0)
+## 🧭 Release Checklist (4.x)
 
 - Run `pnpm run check:release`
-- Run `pnpm version major` (creates `v4.0.0` tag)
+- Bump the version with `pnpm version patch|minor|major` (creates matching git tag, e.g. `v4.1.1`)
+- Push commit + tags (`git push && git push --tags`) so release workflows can run
 - CI publishes to npm automatically
-- Update dist-tags on npm if needed (`latest` → 4.0.0)
+- Update dist-tags on npm if needed (`latest` → current stable)
+
+**Backfill tags if missing:**
+
+```bash
+git tag -a v4.1.0 <commit-sha-for-4.1.0> -m "v4.1.0"
+git tag -a v4.1.1 <commit-sha-for-4.1.1> -m "v4.1.1"
+git push --tags
+```
 
 ## 🔄 Migration Guide (3.x → 4.0)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",

tests/hooks/usePublishedVariables.test.tsx

@@ -514,4 +514,36 @@ describe('usePublishedVariables', () => {
 
     spy.mockRestore()
   })
+
+  it('should use live key when fallbackFile exists but parsedFallbackFile is invalid', () => {
+    const spy = vi
+      .spyOn(useFigmaTokenContextModule, 'useFigmaTokenContext')
+      .mockReturnValue({
+        token: 'test-token',
+        fileKey: 'test-key',
+        fallbackFile: '{invalid-json}',
+        parsedFallbackFile: undefined,
+        providerId: 'test-provider',
+      } as ReturnType<typeof useFigmaTokenContextModule.useFigmaTokenContext>)
+
+    mockedUseSWR.mockReturnValue({
+      data: undefined,
+      error: undefined,
+      isLoading: false,
+      isValidating: false,
+    })
+
+    renderHook(() => usePublishedVariables())
+
+    expect(mockedUseSWR).toHaveBeenCalledWith(
+      [
+        'https://api.figma.com/v1/files/test-key/variables/published',
+        'test-token',
+      ],
+      expect.any(Function),
+      undefined
+    )
+
+    spy.mockRestore()
+  })
 })

tests/hooks/useVariables.test.tsx

@@ -495,4 +495,33 @@ describe('useVariables', () => {
 
     spy.mockRestore()
   })
+
+  it('should use live key when fallbackFile exists but parsedFallbackFile is invalid', () => {
+    const spy = vi
+      .spyOn(useFigmaTokenContextModule, 'useFigmaTokenContext')
+      .mockReturnValue({
+        token: 'test-token',
+        fileKey: 'test-key',
+        fallbackFile: '{invalid-json}',
+        parsedFallbackFile: undefined,
+        providerId: 'test-provider',
+      } as ReturnType<typeof useFigmaTokenContextModule.useFigmaTokenContext>)
+
+    mockedUseSWR.mockReturnValue({
+      data: undefined,
+      error: undefined,
+      isLoading: false,
+      isValidating: false,
+    })
+
+    renderHook(() => useVariables())
+
+    expect(mockedUseSWR).toHaveBeenCalledWith(
+      ['https://api.figma.com/v1/files/test-key/variables/local', 'test-token'],
+      expect.any(Function),
+      undefined
+    )
+
+    spy.mockRestore()
+  })
 })