feat: enhance changelog with sidebar scroll position fixes and improve spec directory handling

Author: tikazyq

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
+- **Web sidebar scroll position drift** (spec 101) - Eliminated scroll position jumping during navigation
+  - Fixed React 19 `useSyncExternalStore` infinite loop by stabilizing server snapshot references
+  - Isolated scroll persistence to prevent global store re-renders on every scroll event
+  - Implemented component-local scroll management with `useIsomorphicLayoutEffect` for flicker-free restoration
+  - Added guarded auto-anchoring that centers active spec on page refresh without disrupting user scrolling
+  - Validated smooth scrolling for 100+ spec lists with no drift during rapid navigation or filtering
 - **Web spec detail page sub-specs display** - Fixed missing sub-specs tabs and count indicator
   - Sub-specs tabs now correctly display when available
   - Sidebar shows sub-spec count (e.g., "+3") for specs with additional markdown files

packages/cli/src/commands/ui.ts

@@ -269,7 +269,7 @@ function buildUiRunner(
   }
 
   if (packageManager === 'pnpm') {
-    const args = ['dlx', '--prefer-offline', ...uiArgs];
+    const args = ['dlx', ...uiArgs];
     return { command: 'pnpm', args, preview: `pnpm ${args.join(' ')}` };
   }
 

packages/web/src/app/api/__tests__/specs.test.ts

@@ -58,7 +58,7 @@ describe('Spec API Routes', () => {
 
       const json = await response.json();
       expect(json).toHaveProperty('spec');
-      expect(json.spec.id).toBe('1');
+      expect(json.spec.id).toBe(mockSpec.id);
 
       // Verify cache headers are present
       const cacheControl = response.headers.get('Cache-Control');

packages/web/src/lib/db/service-queries.ts

@@ -6,7 +6,7 @@
 import { specsService } from '../specs/service';
 import type { Spec } from './schema';
 import { detectSubSpecs } from '../sub-specs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { readFileSync } from 'node:fs';
 import matter from 'gray-matter';
 
@@ -17,6 +17,23 @@ export type ParsedSpec = Omit<Spec, 'tags'> & {
   tags: string[] | null;
 };
 
+const DEFAULT_SPECS_DIR = resolve(process.cwd(), '../../specs');
+
+function getSpecsRootDir(): string {
+  const envDir = process.env.SPECS_DIR;
+  if (!envDir) {
+    return DEFAULT_SPECS_DIR;
+  }
+  return envDir.startsWith('/') ? envDir : resolve(process.cwd(), envDir);
+}
+
+function buildSpecDirPath(filePath: string): string {
+  const normalized = filePath
+    .replace(/^specs\//, '')
+    .replace(/\/README\.md$/, '');
+  return join(getSpecsRootDir(), normalized);
+}
+
 interface SpecRelationships {
   dependsOn: string[];
   related: string[];
@@ -113,7 +130,7 @@ export async function getSpecsWithSubSpecCount(projectId?: string): Promise<(Par
   }
 
   return specs.map(spec => {
-    const specDirPath = join(process.cwd(), '../../specs', spec.filePath.replace('/README.md', '').replace('specs/', ''));
+    const specDirPath = buildSpecDirPath(spec.filePath);
     const subSpecsCount = countSubSpecs(specDirPath);
     return { ...parseSpecTags(spec), subSpecsCount };
   });
@@ -131,7 +148,7 @@ export async function getSpecById(id: string, projectId?: string): Promise<(Pars
 
   // Detect sub-specs from filesystem (only for filesystem mode)
   if (!projectId) {
-    const specDirPath = join(process.cwd(), '../../specs', spec.filePath.replace('/README.md', '').replace('specs/', ''));
+    const specDirPath = buildSpecDirPath(spec.filePath);
     const subSpecs = detectSubSpecs(specDirPath);
     const relationships = getFilesystemRelationships(specDirPath);
     return { ...parsedSpec, subSpecs, relationships };