docs: refine comments and documentation for clarity

Author: eric15342335

README.md

@@ -60,14 +60,14 @@ This guide is for developers maintaining or contributing to this project.
 ```bash
 .
 ├── src/
-│   ├── app/             # Next.js App Router pages and layouts.
+│   ├── app/             # Next.js App Router pages and layouts
 │   ├── components/
-│   │   ├── sections/    # Reusable large components.
-│   │   ├── primitives/  # Reusable small components.
-│   │   └── ui/          # Unmodified shadcn/ui components.
-│   ├── lib/             # Utilities and site configuration.
-│   └── providers/       # App-wide context and state providers.
-├── public/              # Static assets (images, icons).
+│   │   ├── primitives/  # Small components that take little space on the screen
+│   │   ├── sections/    # Large components that can take up the entire screen
+│   │   └── ui/          # Only put shadcn/ui components here for clarity
+│   ├── lib/             # frequently reused functions and data
+│   └── providers/       # App-wide context and state providers
+├── public/              # non-code assets
 ```
 
 ## Working with `shadcn/ui`

src/components/primitives/smart-link.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Will be imported by client components
 import { isInternalHref } from "@/lib/utils";
 import Link from "next/link";
 import { forwardRef, type AnchorHTMLAttributes, type ReactNode } from "react";
@@ -29,6 +30,7 @@ export const SmartLink = forwardRef<HTMLAnchorElement, SmartLinkProps>(function
   }
 
   const computedTarget = target ?? "_blank";
+  // I like referrers; +rep for marketing people
   const computedRel = rel ?? (computedTarget === "_blank" ? "noopener" : undefined);
 
   return (

src/components/sections/coming-soon.tsx

@@ -4,7 +4,7 @@ import { Construction } from "lucide-react";
 export const comingSoonText = "We're working hard to bring you this page. Stay tuned for something amazing!";
 
 export function ComingSoon({ title }: { title?: string }) {
-  const heading = title ? `${title} is Coming Soon!` : "Coming Soon!";
+  const heading = title ? `${title} is Coming Soon!` : "Coming Soon!"; // Make each "Coming Soon" page unique
   return (
     <div className="flex min-h-[calc(100vh-8rem)] flex-col items-center justify-center px-4 text-center">
       <Construction className="text-primary mb-4 h-16 w-16" />

src/components/sections/header.tsx

@@ -180,7 +180,7 @@ export function Header() {
         >
           <motion.div
             initial={false}
-            animate={isOpen ? { opacity: 1, height: "auto" } : { opacity: 0, height: 0 }}
+            animate={isOpen ? { opacity: 1, height: "auto" } : { opacity: 0, height: 0 }} // Closing must be animated to reduce SPA page navigation flash
             transition={{ duration: 0.3, ease: "easeInOut" }}
             className="absolute right-0 left-0 overflow-hidden"
           >

src/components/sections/resource-iframe.tsx

@@ -7,7 +7,7 @@ import { cn, isInternalHref, noReturnDebounce } from "@/lib/utils";
 import { CSSProperties, RefObject, useCallback, useEffect, useRef, useState } from "react";
 
 const IFRAME_DEFAULTS = {
-  WIDTH: 1440,
+  WIDTH: 1440, // Magic! Experiment with this for different iframed websites
   HEIGHT: 600,
 } as const;
 
@@ -31,7 +31,7 @@ function createScaleTransformStyle(scale: number, hideTopPx: number = 0) {
 }
 
 /**
- * A hook to calculate the responsive scale of an element based on its container's width.
+ * Resize the iframe zoom level to fit the container width to make it look normal
  */
 function useResponsiveScale(targetRef: RefObject<HTMLElement | null>, sourceWidth: number): number {
   const [scale, setScale] = useState(1);
@@ -58,17 +58,14 @@ type ResourceIframeProps = {
   className?: string;
   scale?: number;
   desktopWidth?: number;
-  /** Can be a number (px) or CSS height string (e.g. "100dvh"). */
   containerHeight?: number | CSSProperties["height"];
-  /** Number of pixels to hide from the top of the iframe content (pre-scale units). */
+  /** Adjust this to hide Wix/WordPress ad headers */
   hideTopPx?: number;
-  /** Internal link to a full-page view. If provided, the header button links here instead of external site. */
+  /** We host the iframe fullscreen ourselves, so we can link to it */
   fullPageHref?: string;
-  /** If true, omits the header (useful for full-page variant). */
+  /** Useful for the full-page variant, which is just the iframe */
   hideHeader?: boolean;
-  /** If true, shows the iframe on mobile as well (not just md+). */
   showOnMobile?: boolean;
-  /** Optional small text line to display the author information. */
   authorLine?: string;
 };
 

src/lib/config.ts

@@ -74,7 +74,7 @@ export function buildPageMetadata(
     title: label,
     description,
     alternates: {
-      canonical: path === "/" ? "/" : path.replace(/\/$/, ""),
+      canonical: path === "/" ? "/" : path.replace(/\/$/, ""), // Google Search Console; prevents {www.}alphahku.page subdomain issues
     },
     openGraph: {
       title: label,

src/lib/utils.ts

@@ -19,6 +19,7 @@ export function noReturnDebounce<T extends unknown[]>(
   };
 }
 
+// For SPA route detection
 export function isInternalHref(href: string): boolean {
   if (!href) return false;
   if (!href.startsWith("/")) return false;