skills-showcase Documentation Pass

Added /* === Section === */ markers to both globals.css (~1260 lines) and workflow.css (~620 lines) to create navigable regions. Two inline WHY comments were also added in globals.css.

app/globals.css

/* Force light scheme so blueprint grid and card surfaces render consistently
   regardless of OS dark-mode preference. */

/* Two overlapping 1px repeating gradients produce a 48px blueprint grid
   visible behind every page - the signature visual motif of the showcase. */

app/prototype/prototype.css

/* Shimmer-foil: a diagonal highlight sweep that mimics metallic foil catching
   light, used on dark-surface cards to draw attention without layout shift. */

src/showcase/tui/workflow.css

/* Subtle rotations give the notebook a hand-pinned-to-corkboard feel;
   the component cycles through tilt classes on each workflow step change. */

Module-level blocks and inline WHY comments for the app shell (root layout, page, prototype page).

app/layout.tsx

/*
 * Root layout - loads skills-data.js and github-proof-data.js via
 * <Script strategy="beforeInteractive"> so the catalog JSON lands on
 * window.SKILLS_SHOWCASE_DATA before React hydration. Client components
 * read this directly instead of making an API call.
 */

app/page.tsx

{/* Renders after the server HTML so it can imperatively populate
    [data-workflow-preview] hooks in the DOM above. */}

app/prototype/page.tsx

/*
 * Pack-opening prototype page - animation debug harness for the
 * sealed-pack tear / open / drawer sequence. Used to iterate on
 * motion timing and state transitions outside the production routes.
 */

// Debug harness drives pack index 0 ("global") through the exact
// production callbacks via this imperative handle. Index 0 is the
// canonical test target so every debug session starts deterministic.

{/* LayoutGroup scopes framer-motion's shared layout animations (layoutId
    morphs) so packs don't interfere with each other during transitions. */}

Module-level blocks and inline WHY comments for the debug visualization and control components.

src/components/BottomSheet.tsx

/**
 * BottomSheet.tsx - slide-up drawer container for the pack-opener content.
 *
 * AnimatePresence exit drives the close morph-back sequence: when isOpen flips
 * false the sheet slides out, and onExitComplete fires the chain that clears
 * openPack and lets the shared-layout card morph back to the SealedPack.
 */

// Track prior open state in a ref so the effect below can detect the
// open-to-closed transition and trigger exit animation before AnimatePresence
// unmounts the children.

// Dismiss is disabled during collapse so the user can't tap the scrim
// mid-animation, which would break the close sequence ordering.

src/components/CardFace.tsx

// Grading thresholds are UX decisions (not statistical boundaries):
// 80%+ = A (green), 50-79% = B (yellow), below 50% = C (red).

src/components/PackOpener.tsx

// Card 0 owns the shared layoutId, so framer controls its animate prop
// for the morph. Drive collapse imperatively via motion values instead.

src/components/debug/AnimationMachineGraph.tsx

/**
 * AnimationMachineGraph.tsx - SVG visualization of the animation state machine.
 *
 * Driven by the canonical model from animationMachine.ts, renders live snapshot
 * state: active, reached, paused, blocked, and reset nodes/transitions are
 * color-coded so the current point in the open/close sequence is visible at a
 * glance inside the debug panel.
 */

// Same-lane: vertical arc (curveY offset above the lane) so the path stays
// visible above the node boxes. Cross-lane: S-curve with control points at
// each lane's Y for clean routing between rows.

src/components/debug/DebugController.tsx

// If something is already parked (shouldn't happen in a sequential chain
// but can during rapid resets), release it to avoid a deadlock before
// parking the new boundary.

src/components/debug/DebugPanel.tsx

/**
 * DebugPanel.tsx - fixed-position debug overlay for /prototype.
 *
 * Controls animation speed, stepping mode, and displays live state from the
 * animation machine. Designed to stay out of the way during normal use (a
 * single gear button) and expand into a full instrumentation panel on demand.
 */

// Surfaced in the panel so the chosen slow-mo approach is visible at a glance
// and future devs know the manual clock was evaluated and rejected - see
// manualClock.ts for the full investigation log.

src/components/debug/animationMachine.ts

/**
 * animationMachine.ts - canonical model for the pack-opening state machine.
 *
 * This single definition is consumed by the live debug panel, the static HTML
 * reference page, and integration tests. Keeping one source of truth prevents
 * documentation/code drift: change a node or transition here and every consumer
 * picks it up automatically.
 */

// Hand-positioned constants - visual spacing for the SVG graph lanes.
// These are design decisions for readability, not data-derived values.

// Marks high-value freeze points in the close sequence where the
// shared-layout morph flash occurs - the bug this harness was built to catch.

// Dot-paths into AnimationMachineSnapshot - buildAnimationMachineSnapshot
// reads these to determine which nodes are active/blocked/reset.

src/components/debug/animationMachineStaticPage.ts

/**
 * animationMachineStaticPage.ts - self-contained HTML reference page generator.
 *
 * Reads the same AnimationMachineModel used by the live debug panel so the
 * static docs can never drift from the code. Tests compare the embedded JSON
 * blob with the TypeScript export to enforce this invariant.
 */

Module-level blocks and inline WHY comments for the imperative DOM renderer components and showcase shell.

src/showcase/ShowcaseShell.tsx

/**
 * Invisible render-null component that wires client-side interactivity
 * (mobile menu toggle, Escape key handler) onto the server-rendered header.
 * Returns null - exists purely for side effects. Keeps the header as plain
 * server-rendered HTML (fast initial paint, SEO) while adding JS behavior.
 */

src/showcase/benchmarks.tsx

/**
 * Imperative DOM renderer for the benchmarks section - same pattern as
 * catalog.tsx: finds `data-*` hooks in server-rendered HTML and injects
 * benchmark cards/tables.
 */

// Multi-platform skills (claude/codex) share a mirrorKey - dedup so each
// logical skill gets one benchmark row regardless of platform variants.

src/showcase/catalog.tsx

/**
 * Imperative DOM renderer for the catalog page.
 * The page is server-rendered HTML with `data-*` attribute hooks; this client
 * component hydrates by finding those hooks and injecting dynamic content
 * (skill cards, pack maps, benchmarks). This avoids re-rendering the entire
 * page as a client component while still adding interactivity.
 */

// Skills can appear in multiple platform variants (claude/codex) sharing
// the same mirrorKey - dedup prevents double-counting in the catalog view.

src/showcase/newsletter-form.tsx

/**
 * Controlled newsletter subscription form with a state machine
 * (ready -> invalid-email/pending -> success/error). Validates email
 * client-side before hitting the tRPC endpoint.
 */

src/showcase/workflows.tsx

/**
 * Imperative DOM renderer for the workflow selector section.
 * Populates workflow preview cards in the server-rendered page shell.
 * TuiWorkflow.tsx is the full interactive player mounted separately -
 * two different UIs for different contexts (preview vs full playback).
 */

src/hooks/useSkillsData.ts

/**
 * Client-side hook that reads skill catalog data from window.SKILLS_SHOWCASE_DATA.
 * The data is injected by a <Script strategy="beforeInteractive"> tag in the root
 * layout that loads a pre-built JSON file.
 */

// The Script tag loads before hydration but after the module graph -
// there's a race window where the hook mounts before the script has
// executed, so we poll until the global appears.

Module-level blocks and inline WHY comments for the TUI workflow subsystem.

src/showcase/tui/TuiWorkflow.tsx

/**
 * Terminal-style workflow player that renders AFPS phase walkthroughs as a TUI
 * notebook with typewriter animation, benchmark injection, and step-by-step
 * playback. Pairs useWorkflowPlayer (state machine) with useTypewriter (reveal
 * animation) to orchestrate the full playback experience.
 */

// Gates auto-advance: prevents advancing to the next step before the
// typewriter animation finishes revealing the current agent response.
// Without this, auto-advance would skip partially-typed content.

// Same injection pattern as useSkillsData - data arrives via beforeInteractive
// Script tag on window, not props or API call.

// Cycles through 7 CSS notebook tilt transforms (rotation + shadow) so each
// workflow gets a distinct visual angle without needing per-workflow config.

src/showcase/tui/shared/useTypewriter.ts

/**
 * Character-at-a-time text reveal hook for the TUI workflow player's agent
 * response animation. Returns the progressively-revealed substring and a
 * `done` flag that gates downstream playback logic.
 */

// Ref instead of state for the character index: avoids a re-render on every
// tick. The ref holds the mutable cursor; only `displayed` (the sliced
// string) triggers a render - one setState per tick instead of two.

src/showcase/tui/shared/useWorkflowPlayer.ts

/**
 * State machine hook for the TUI workflow player - manages active workflow,
 * step index, playback state, and reduced-motion preferences. Exposes
 * navigation primitives (next/prev/goTo/restart) consumed by TuiWorkflow.
 */

// High-water mark: only increases. Tracks the furthest step the user has
// seen so the transcript shows all previously-revealed steps. activeStep
// can go backwards (via prevStep); revealedStep cannot.

// canAutoAdvance: the parent (TuiWorkflow) sets this to false while typewriter
// animation is in progress, gating auto-advance until content is fully revealed.

src/showcase/tui/workflow-data.ts

/**
 * Static workflow definitions for the AFPS (Agentic Full-Product Stack) phase
 * walkthroughs. Each workflow describes a product development phase with steps,
 * replay blocks, and metadata for the TUI notebook player.
 */

// Factory: auto-generates the replay block structure (user/agent/terminal/
// artifact/receipt) from just title, command, and summary - keeps workflow
// definitions declarative and prevents replay structure drift across 30+ steps.

// "benchmark" receipts are dynamically populated from persisted benchmark
// evidence at render time; "curated" receipts use static placeholder text.
// The distinction drives conditional rendering in TuiWorkflow.

Module-level blocks, inline WHY comments, and a SQL contract comment for the tRPC layer and database access.

src/db/index.ts

/**
 * Neon serverless SQL access layer for the newsletter subscriber database.
 */

-- ON CONFLICT re-activates so users who previously unsubscribed can
-- re-subscribe by simply submitting the form again, without a separate
-- reactivation flow.

src/trpc/init.ts

/**
 * tRPC initialization with context creation.
 * protectedProcedure gates admin endpoints behind HMAC session tokens.
 */

// tRPC's fetch adapter only exposes raw headers (FetchCreateContextFnOptions
// has no parsed cookies), so we parse the cookie header ourselves.

src/trpc/newsletter.ts

/**
 * Newsletter subscription (public) and admin CRUD (protected) endpoints.
 */

// Per-IP sliding window stored in the database rather than in-memory,
// because serverless instances don't share memory across invocations.

// Hand-rolled instead of pulling a CSV library - single-use, three-line
// implementation; a library would be heavier than the function itself.

src/trpc/provider.tsx

/**
 * Client-side tRPC + React Query provider.
 */

// useState(() => ...) initializer prevents re-creation on every render.
// Without this, each render would create new client instances, breaking
// React Query's cache and causing infinite refetch loops.

Representative subset of ~15 comments mapped to their justification for existence.

Use feedback YAML for revision requests before final approval. Use final answers after all required gates are answered.

Required questions remaining: 5