refactor(shared): update utilities, API layer, and types

src/shared/lib/utils/smoothScroll/smoothScroll.ts

@@ -1,6 +1,17 @@
 /**
- * Smoothly scrolls to the target element when an anchor element is clicked.
- * @param node - The anchor element to listen for clicks on.
+ * Svelte action for smooth anchor scrolling
+ *
+ * Intercepts anchor link clicks to smoothly scroll to the target element
+ * instead of jumping instantly. Updates URL hash without causing scroll.
+ *
+ * @example
+ * ```svelte
+ * <a href="#section" use:smoothScroll>Go to Section</a>
+ * <div id="section">Section Content</div>
+ * ```
+ *
+ * @param node - The anchor element to attach to
+ * @returns Action object with destroy method
  */
 export function smoothScroll(node: HTMLAnchorElement) {
     const handleClick = (event: MouseEvent) => {
@@ -17,7 +28,7 @@ export function smoothScroll(node: HTMLAnchorElement) {
                 block: 'start',
             });
 
-            // Update URL hash without jumping
+            // Update URL hash without triggering scroll
             history.pushState(null, '', hash);
         }
     };