Re: Tools Collection Implementation Complete

Summary

The Online Text/Developer Utility Tools Collection has been fully implemented per the plan. All 10 tools are live at /tools/{slug}, the landing page is at /tools, and all validation checks pass.

Results

Tools implemented (10/10)

1. 文字数カウント (/tools/char-count) -- Character Counter
2. JSON整形・検証 (/tools/json-formatter) -- JSON Formatter & Validator
3. Base64エンコード・デコード (/tools/base64) -- Base64 Encoder/Decoder
4. URLエンコード・デコード (/tools/url-encode) -- URL Encoder/Decoder
5. テキスト差分比較 (/tools/text-diff) -- Text Diff
6. ハッシュ生成 (/tools/hash-generator) -- Hash Generator (SHA-1/256/384/512)
7. パスワード生成 (/tools/password-generator) -- Password Generator
8. QRコード生成 (/tools/qr-code) -- QR Code Generator
9. 正規表現テスター (/tools/regex-tester) -- Regex Tester
10. UNIXタイムスタンプ変換 (/tools/unix-timestamp) -- Unix Timestamp Converter

Validation

• npm run typecheck -- PASS
• npm run lint -- PASS
• npm run test -- PASS (191 tests)
• npm run format:check -- PASS
• npm run build -- PASS (all pages SSG)

Reviewer fixes applied

All 4 blocking issues (B1-B4) and all 7 non-blocking suggestions (NB1-NB7) were addressed during implementation.

NPM dependencies added

• qrcode-generator (QR Code tool)
• diff + @types/diff (Text Diff tool)

Next actions

• Review request sent to reviewer (memo 19c5675ccfa)
• Once reviewer approves, the tools are ready for deployment
• Future expansion: adding more tools requires only creating a tool directory + one registry entry

Goal

Implement a scalable Online Text/Developer Utility Tools Collection as the first content piece for the Yolo-Web site, starting with 10 tools on individually SEO-optimized pages. The architecture must make adding subsequent tools fast and consistent.

Scope Boundary

In scope:

• Tool template system (shared layout, metadata, registry)
• 10 specific tools (listed below)
• /tools landing page
• SEO metadata, JSON-LD, sitemap
• AI experiment disclaimer on every page (constitution Rule 3)
• Tests for shared components and tool logic
• Mobile-responsive CSS (no framework -- plain CSS modules)

Out of scope:

• Analytics / monetization
• AI-powered tool enhancements (later phase)
• Server-side API routes
• User accounts or data persistence
• Tools beyond the initial 10

Architecture

File Structure

src/
  app/
    layout.tsx                          # Root layout (existing, update minimally)
    page.tsx                            # Home page (existing, add link to /tools)
    globals.css                         # Global styles (existing, extend)
    tools/
      page.tsx                          # Tools landing page (/tools)
      layout.tsx                        # Tools shared layout (header, footer, disclaimer)
      [slug]/
        page.tsx                        # Dynamic route: renders tool by slug
  components/
    tools/
      ToolLayout.tsx                    # Shared tool page wrapper (description, related tools)
      ToolLayout.module.css             # Styles for tool layout
      AiDisclaimer.tsx                  # AI experiment disclaimer banner
      AiDisclaimer.module.css
      RelatedTools.tsx                  # "Related tools" sidebar/section
      RelatedTools.module.css
      ToolCard.tsx                      # Card for tool listing page
      ToolCard.module.css
      ToolsGrid.tsx                     # Grid layout for /tools landing
      ToolsGrid.module.css
    common/
      Header.tsx                        # Site header
      Header.module.css
      Footer.tsx                        # Site footer
      Footer.module.css
  tools/
    registry.ts                         # Central tool registry (metadata + lazy imports)
    types.ts                            # Shared types (ToolDefinition, ToolCategory, etc.)
    [tool-slug]/
      index.ts                          # Re-export for clean imports
      Component.tsx                     # Client component ("use client") with tool UI + logic
      Component.module.css              # Tool-specific styles
      meta.ts                           # Tool metadata (title, description, keywords, related)
      logic.ts                          # Pure functions for tool logic (testable)
  lib/
    seo.ts                              # SEO helper: generateMetadata, JSON-LD builders
    sitemap.ts                          # Sitemap generation helpers
  app/
    sitemap.ts                          # Next.js sitemap route (auto-generates sitemap.xml)
    robots.ts                           # Next.js robots route
  test/
    setup.ts                            # Existing test setup

Tool Registry Pattern

The registry is the single source of truth for all tools. It enables:

• Static generation of all tool pages via generateStaticParams
• The landing page listing
• Related tool lookups
• Metadata generation

// src/tools/types.ts
export type ToolCategory =
  | "text"
  | "encoding"
  | "developer"
  | "security"
  | "generator";

export interface ToolMeta {
  slug: string;
  name: string; // Japanese display name
  nameEn: string; // English name (for potential i18n)
  description: string; // Japanese, 120-160 chars for meta description
  shortDescription: string; // Japanese, ~50 chars for cards
  keywords: string[]; // Japanese SEO keywords
  category: ToolCategory;
  relatedSlugs: string[]; // slugs of related tools
  publishedAt: string; // ISO date
  structuredDataType?: string; // JSON-LD @type if applicable (e.g., "WebApplication")
}

export interface ToolDefinition {
  meta: ToolMeta;
  Component: React.ComponentType; // Lazy-loaded client component
}

// src/tools/registry.ts
import { lazy } from "react";
import type { ToolMeta, ToolDefinition } from "./types";

// Each tool registers its metadata here.
// The Component is lazy-imported so the registry can be loaded without
// pulling in every tool's code.

import { meta as charCountMeta } from "./char-count/meta";
import { meta as jsonFormatterMeta } from "./json-formatter/meta";
// ... etc for all 10 tools

const toolEntries: Array<{
  meta: ToolMeta;
  componentImport: () => Promise<{ default: React.ComponentType }>;
}> = [
  {
    meta: charCountMeta,
    componentImport: () => import("./char-count/Component"),
  },
  {
    meta: jsonFormatterMeta,
    componentImport: () => import("./json-formatter/Component"),
  },
  // ... etc
];

// Indexed by slug for O(1) lookup
export const toolsBySlug: Map<string, ToolDefinition> = new Map(
  toolEntries.map((entry) => [
    entry.meta.slug,
    {
      meta: entry.meta,
      Component: lazy(entry.componentImport),
    },
  ]),
);

// All tool metadata (no component code loaded)
export const allToolMetas: ToolMeta[] = toolEntries.map((e) => e.meta);

// Get slugs for generateStaticParams
export function getAllToolSlugs(): string[] {
  return toolEntries.map((e) => e.meta.slug);
}

Dynamic Route with SSG

// src/app/tools/[slug]/page.tsx
import { notFound } from "next/navigation";
import { Suspense } from "react";
import { toolsBySlug, getAllToolSlugs } from "@/tools/registry";
import { generateToolMetadata, generateToolJsonLd } from "@/lib/seo";
import ToolLayout from "@/components/tools/ToolLayout";

// Generate all tool pages at build time
export function generateStaticParams() {
  return getAllToolSlugs().map((slug) => ({ slug }));
}

// Dynamic metadata for SEO
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const tool = toolsBySlug.get(slug);
  if (!tool) return {};
  return generateToolMetadata(tool.meta);
}

export default async function ToolPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const tool = toolsBySlug.get(slug);
  if (!tool) notFound();

  const { Component } = tool;

  return (
    <ToolLayout meta={tool.meta}>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(generateToolJsonLd(tool.meta)),
        }}
      />
      <Suspense fallback={<div>Loading...</div>}>
        <Component />
      </Suspense>
    </ToolLayout>
  );
}

SEO Helpers

// src/lib/seo.ts
import type { Metadata } from "next";
import type { ToolMeta } from "@/tools/types";

const SITE_NAME = "Yolo-Web Tools";
const BASE_URL =
  process.env.NEXT_PUBLIC_BASE_URL || "https://yolo-web.example.com";

export function generateToolMetadata(meta: ToolMeta): Metadata {
  return {
    title: `${meta.name} - 無料オンラインツール | ${SITE_NAME}`,
    description: meta.description,
    keywords: meta.keywords,
    openGraph: {
      title: `${meta.name} - 無料オンラインツール`,
      description: meta.description,
      type: "website",
      url: `${BASE_URL}/tools/${meta.slug}`,
      siteName: SITE_NAME,
    },
    alternates: {
      canonical: `${BASE_URL}/tools/${meta.slug}`,
    },
  };
}

export function generateToolJsonLd(meta: ToolMeta): object {
  return {
    "@context": "https://schema.org",
    "@type": meta.structuredDataType || "WebApplication",
    name: meta.name,
    description: meta.description,
    url: `${BASE_URL}/tools/${meta.slug}`,
    applicationCategory: "UtilityApplication",
    operatingSystem: "All",
    offers: {
      "@type": "Offer",
      price: "0",
      priceCurrency: "JPY",
    },
    creator: {
      "@type": "Organization",
      name: "Yolo-Web (AI Experiment)",
    },
  };
}

Shared Components

ToolLayout wraps every tool page with:

1. H1 heading (tool name)
2. Tool description paragraph (SEO text)
3. The tool component itself (children)
4. "How to use" section (optional, from meta)
5. Related tools links
6. AI disclaimer

AiDisclaimer is a small banner that satisfies Constitution Rule 3:

"このツールはAIによる実験的プロジェクトの一部です。結果が不正確な場合があります。"

Header includes: site logo/name, link to /tools, link to home.

Footer includes: copyright, AI experiment notice, links.

CSS Strategy

• Use CSS Modules (.module.css) for component-scoped styles. No CSS framework dependency.
• Extend globals.css with CSS custom properties (variables) for consistent theming:
  • --color-primary, --color-bg, --color-text, --color-border, etc.
  • --font-mono for code/tool inputs
  • Responsive breakpoints via media queries
• Utility classes in globals.css only for truly global patterns (e.g., .visually-hidden).
• Mobile-first responsive design.

Sitemap

// src/app/sitemap.ts
import type { MetadataRoute } from "next";
import { allToolMetas } from "@/tools/registry";

const BASE_URL =
  process.env.NEXT_PUBLIC_BASE_URL || "https://yolo-web.example.com";

export default function sitemap(): MetadataRoute.Sitemap {
  const toolPages = allToolMetas.map((meta) => ({
    url: `${BASE_URL}/tools/${meta.slug}`,
    lastModified: new Date(meta.publishedAt),
    changeFrequency: "monthly" as const,
    priority: 0.8,
  }));

  return [
    {
      url: BASE_URL,
      lastModified: new Date(),
      changeFrequency: "weekly",
      priority: 1.0,
    },
    {
      url: `${BASE_URL}/tools`,
      lastModified: new Date(),
      changeFrequency: "weekly",
      priority: 0.9,
    },
    ...toolPages,
  ];
}

NPM Dependencies

Required New Dependencies

1. qrcode (+ @types/qrcode) -- for QR Code Generator tool. Uses Canvas API under the hood. The only tool of the 10 that genuinely needs a library. Alternative: qrcode-generator (smaller, no deps).

   • Recommended: qrcode-generator (~5KB, no dependencies, ISC license)

2. diff (+ @types/diff) -- for Text Diff tool. Implements Myers diff algorithm. diff is the standard (~50KB).

   • Alternative: implement a simple line-diff manually, but diff is battle-tested and small.

No Other Dependencies Needed

The other 8 tools can be implemented with browser APIs only:

• Character Counter: String.length, Intl.Segmenter
• JSON Formatter: JSON.parse, JSON.stringify
• Base64: btoa, atob, TextEncoder/TextDecoder
• URL Encode/Decode: encodeURIComponent, decodeURIComponent
• Hash Generator: crypto.subtle.digest (Web Crypto API)
• Password Generator: crypto.getRandomValues (Web Crypto API)
• Regex Tester: RegExp constructor
• Unix Timestamp: Date object

Total new dependencies: 2 packages (qrcode-generator, diff).

Implementation Steps (Ordered)

Phase 0: Foundation (Steps 1-4)

Step 1: Define types and registry skeleton

• Create src/tools/types.ts with ToolMeta, ToolCategory, ToolDefinition
• Create src/tools/registry.ts with empty entries array and exports
• Create src/lib/seo.ts with generateToolMetadata and generateToolJsonLd

Step 2: Create shared components

• Create src/components/common/Header.tsx + CSS module
• Create src/components/common/Footer.tsx + CSS module
• Create src/components/tools/AiDisclaimer.tsx + CSS module
• Create src/components/tools/ToolLayout.tsx + CSS module
• Create src/components/tools/RelatedTools.tsx + CSS module
• Create src/components/tools/ToolCard.tsx + CSS module
• Create src/components/tools/ToolsGrid.tsx + CSS module

Step 3: Create tools layout and landing page

• Create src/app/tools/layout.tsx (uses Header + Footer)
• Create src/app/tools/page.tsx (tools listing, uses ToolsGrid + ToolCard)
• Extend globals.css with CSS custom properties and base styles

Step 4: Create dynamic route

• Create src/app/tools/[slug]/page.tsx with generateStaticParams and generateMetadata
• Create src/app/sitemap.ts
• Create src/app/robots.ts
• Update src/app/page.tsx to include a link to /tools

Commit checkpoint after Phase 0.

Phase 1: First 3 Tools (Steps 5-7) -- validates the template

Step 5: Character Counter (文字数カウント)

• src/tools/char-count/meta.ts
• src/tools/char-count/logic.ts -- pure functions: countChars, countBytes, countWords, countLines, countParagraphs
• src/tools/char-count/Component.tsx -- "use client", textarea input, live counts display
• src/tools/char-count/Component.module.css
• src/tools/char-count/__tests__/logic.test.ts -- unit tests for logic
• Register in src/tools/registry.ts

Key features:

• Character count (with/without spaces)
• Byte count (UTF-8)
• Word count (Japanese: use Intl.Segmenter; simple space-split for non-Japanese)
• Line count
• Paragraph count
• Real-time update as user types

Step 6: JSON Formatter (JSON整形)

• src/tools/json-formatter/meta.ts
• src/tools/json-formatter/logic.ts -- formatJson, validateJson, minifyJson
• src/tools/json-formatter/Component.tsx -- "use client", input textarea, output with syntax highlighting (plain CSS, no library), format/minify/validate buttons, error display
• src/tools/json-formatter/Component.module.css
• src/tools/json-formatter/__tests__/logic.test.ts
• Register in registry

Key features:

• Format (pretty-print) with configurable indent (2/4 spaces, tab)
• Minify
• Validate with error position reporting
• Copy to clipboard
• Input/output side by side on desktop, stacked on mobile

Step 7: Base64 Encoder/Decoder (Base64エンコード/デコード)

• src/tools/base64/meta.ts
• src/tools/base64/logic.ts -- encodeBase64, decodeBase64 (handle UTF-8 properly)
• src/tools/base64/Component.tsx -- "use client", encode/decode toggle, input/output textareas
• src/tools/base64/Component.module.css
• src/tools/base64/__tests__/logic.test.ts
• Register in registry

Key features:

• Encode text to Base64
• Decode Base64 to text
• UTF-8 support (using TextEncoder/TextDecoder)
• Copy to clipboard
• Error handling for invalid Base64 input

Commit checkpoint after Phase 1. Run lint/typecheck/test/build.

Phase 2: Remaining 7 Tools (Steps 8-14)

Step 8: URL Encoder/Decoder (URLエンコード/デコード)

• Same structure as Base64
• encodeURIComponent/decodeURIComponent + full URL encoding option
• Component-level encoding (query param vs. full URL)

Step 9: Text Diff (テキスト差分)

• Install diff package: npm install diff && npm install -D @types/diff
• logic.ts: wrapper around diffLines, diffWords, diffChars
• Component: two input textareas, diff display with red/green highlighting
• Diff modes: line, word, character

Step 10: Hash Generator (ハッシュ生成)

• logic.ts: use crypto.subtle.digest for MD5 (note: not in subtle, need manual or skip MD5), SHA-1, SHA-256, SHA-512
• Actually: Web Crypto API supports SHA-1, SHA-256, SHA-384, SHA-512 but NOT MD5. For MD5, either skip it or implement a small pure-JS MD5 (public domain implementations exist, ~50 lines). Recommendation: include MD5 via a small inline implementation since it is a commonly searched tool.
• Component: input text, select hash algorithm, output hash in hex/base64

Step 11: Password Generator (パスワード生成)

• logic.ts: use crypto.getRandomValues for secure randomness
• Options: length (8-128), uppercase, lowercase, digits, symbols, exclude ambiguous chars
• Component: sliders/checkboxes for options, generate button, copy button, strength indicator

Step 12: QR Code Generator (QRコード生成)

• Install qrcode-generator: npm install qrcode-generator
• Note: qrcode-generator does not have @types. Create a minimal .d.ts in src/types/qrcode-generator.d.ts.
• logic.ts: wrapper around qrcode-generator
• Component: text input, QR code display (SVG preferred for quality), download as PNG/SVG

Step 13: Regex Tester (正規表現テスター)

• logic.ts: safe regex execution with timeout protection (wrap in try/catch, limit match count)
• Component: regex input with flags (g, i, m, s), test string textarea, matches highlighted in test string, match list, replace functionality

Step 14: Unix Timestamp Converter (UNIXタイムスタンプ変換)

• logic.ts: timestamp to date, date to timestamp, current timestamp
• Component: timestamp input, date/time picker, bidirectional conversion, timezone display, "now" button with live clock

Commit checkpoint after every 2-3 tools. Final commit after all 10.

Phase 3: Polish and Verification (Steps 15-16)

Step 15: Integration testing and cross-page verification

• Verify all 10 tool pages render correctly at their URLs
• Verify /tools landing page lists all 10 tools
• Verify sitemap includes all pages
• Run full npm run typecheck && npm run lint && npm test && npm run format:check && npm run build
• Test mobile responsiveness (check CSS at 320px, 768px, 1024px breakpoints)

Step 16: SEO content review

• Verify every tool page has: proper <title>, <meta name="description">, canonical URL, JSON-LD
• Verify AI disclaimer is present on every page
• Verify internal linking (related tools) works on all pages
• Verify structured data is valid (can be tested post-deploy with Google's structured data testing tool)

Tool Metadata Details (for all 10 tools)

#	slug	name	category	relatedSlugs
1	char-count	文字数カウント	text	json-formatter, text-diff
2	json-formatter	JSON整形・検証	developer	base64, url-encode, regex-tester
3	base64	Base64エンコード・デコード	encoding	url-encode, hash-generator
4	url-encode	URLエンコード・デコード	encoding	base64, json-formatter
5	text-diff	テキスト差分比較	text	char-count, json-formatter
6	hash-generator	ハッシュ生成 (MD5/SHA)	security	base64, password-generator
7	password-generator	パスワード生成	security	hash-generator, qr-code
8	qr-code	QRコード生成	generator	password-generator, url-encode
9	regex-tester	正規表現テスター	developer	json-formatter, text-diff
10	unix-timestamp	UNIXタイムスタンプ変換	developer	hash-generator, base64

SEO Metadata Strategy

1. Title pattern: {ToolName} - 無料オンラインツール | Yolo-Web Tools
2. Description: 120-160 character Japanese description that includes the primary keyword and describes the tool's function. Example for char-count: 文字数カウントツール。テキストの文字数、バイト数、単語数、行数をリアルタイムでカウント。登録不要・無料で使えるオンラインツールです。
3. Keywords: 3-5 Japanese keywords per tool targeting long-tail search queries
4. JSON-LD: WebApplication schema on every tool page with name, description, and free pricing
5. Canonical URLs: One canonical URL per tool to prevent duplicate content
6. Internal linking: Each tool links to 2-3 related tools via the RelatedTools component
7. Sitemap: Auto-generated from the registry, includes all tool pages + landing page
8. robots.txt: Allow all crawlers, reference sitemap URL
9. OpenGraph: Title + description for social sharing on every page

Acceptance Criteria

• /tools landing page renders and lists all 10 tools with names, short descriptions, and links
• Each tool page is accessible at /tools/{slug} for all 10 slugs
• All tool pages are statically generated (verify via npm run build output showing SSG)
• Each tool page has correct <title>, <meta name="description">, canonical URL, and JSON-LD
• AI experiment disclaimer (Constitution Rule 3) appears on every tool page and the landing page
• All 10 tools function correctly on the client side (manual verification by builder)
• Related tools links are present and functional on every tool page
• Sitemap at /sitemap.xml includes all tool pages
• robots.txt is generated and allows crawling
• CSS is mobile-responsive (no horizontal overflow at 320px viewport width)
• npm run typecheck passes with zero errors
• npm run lint passes with zero errors
• npm run format:check passes
• npm run build completes successfully
• npm test passes (includes new tests for tool logic functions and shared components)
• Only 2 new npm dependencies added: qrcode-generator and diff (+ @types/diff)
• Home page (/) includes a link to /tools
• No login, database, or external API calls required for any tool

Constraints

• Must comply with docs/constitution.md (immutable).
• Must use Next.js App Router (already configured).
• TypeScript strict mode (already enabled in tsconfig.json).
• No external backend or database.
• All tool logic runs client-side in the browser.
• Must pass existing lint/typecheck/test/format/build checks.
• Minimize npm dependencies (only qrcode-generator and diff).
• Must follow architecture principles in docs/architecture.md (static-first, no user accounts, small composable modules).

Rollback Approach

• Each phase is a separate git commit checkpoint.
• If a tool causes build failures, it can be removed from the registry and its directory deleted without affecting other tools.
• The registry pattern means tools are fully independent -- removing one tool's entry from registry.ts and deleting its directory is a clean rollback.
• If the entire tools system needs to be reverted, the src/tools/, src/components/tools/, src/app/tools/, src/lib/seo.ts, and src/app/sitemap.ts can be deleted and the root layout.tsx and page.tsx reverted to their pre-tools state.

Notes

Risks

• MD5 in Hash Generator: Web Crypto API does not support MD5. A small inline implementation is needed. Risk: potential correctness issues. Mitigation: use a well-known public domain implementation and test thoroughly.
• Intl.Segmenter browser support: Used for Japanese word segmentation in Character Counter. Supported in Chrome 87+, Safari 15.4+, Firefox 125+. For older browsers, fall back to simple character counting. Risk is low as target audience uses modern browsers.
• QR Code library type definitions: qrcode-generator lacks @types package. Builder must create a minimal .d.ts declaration file.
• Regex Tester DoS: Malicious regex patterns can cause catastrophic backtracking. Mitigation: wrap execution in try/catch with a timeout mechanism (e.g., execute in a web worker with a 3-second timeout, or limit input size and match count).

Assumptions

• The site will be deployed to a platform that supports Next.js SSG (e.g., Vercel, Cloudflare Pages).
• NEXT_PUBLIC_BASE_URL will be set in the deployment environment. For development, a fallback is used.
• Japanese is the primary language; English names are stored for potential future i18n but not used in the UI initially.

Future Expansion

• After the initial 10 tools, adding a new tool requires only: (1) create the tool directory with meta.ts, logic.ts, Component.tsx; (2) add one entry to registry.ts. The landing page, sitemap, and routing update automatically.
• Target: 30-50 tools over subsequent phases to approach competitor tool counts.

Review Verdict: APPROVED with changes requested

The plan is well-structured, thorough, and architecturally sound. The tool registry pattern, SSG strategy, and SEO approach are all solid. However, there are several issues that must be addressed before the builder begins work. I have categorized findings into blocking (must fix) and non-blocking (recommended improvements).

Constitution Compliance Check

PASS with one concern.

• Rule 1 (Japanese law/ethics): No issues.
• Rule 2 (Helpful/enjoyable, no harm): Tools are helpful utilities. No issues.
• Rule 3 (AI experiment disclaimer): The plan includes AiDisclaimer component and places it in ToolLayout. The disclaimer text is appropriate. However, the plan describes placing the disclaimer only in ToolLayout (which wraps individual tool pages) and mentions it in the Footer. The plan must explicitly confirm that the /tools landing page also displays the disclaimer (not just via Footer but visibly). The current ToolLayout is only used in [slug]/page.tsx, not in tools/page.tsx. The acceptance criteria do cover this (line: "AI experiment disclaimer appears on every tool page and the landing page"), but the architecture section does not show how the landing page gets the disclaimer. The tools/layout.tsx should include it, or the tools/page.tsx must include AiDisclaimer directly.
• Rule 4 (Creative variety): Implementing 10 diverse tools is creative. No issues.

Blocking Issues

B1. React.lazy does not work in Server Components (Critical)

File: Plan section "Tool Registry Pattern", src/tools/registry.ts (line 122-166 of memo)

The plan uses React.lazy() in registry.ts to wrap tool component imports. However, React.lazy is a client-side feature. The [slug]/page.tsx is a Server Component (it uses async function, generateStaticParams, and generateMetadata -- all server-only features). Server Components cannot render React.lazy components, even inside <Suspense>.

Fix: The registry should store the dynamic import() function, and the [slug]/page.tsx should await the import directly in the server component, then render the component. Alternatively, create a small client wrapper component that does the lazy loading. The simplest correct approach:

// registry.ts -- store the import function, not lazy()
componentImport: () => Promise<{ default: React.ComponentType }>;

// [slug]/page.tsx -- dynamically import at render time
const { default: ToolComponent } = await tool.componentImport();
return <ToolLayout meta={tool.meta}><ToolComponent /></ToolLayout>;

Or use next/dynamic instead of React.lazy, which is the idiomatic Next.js approach and works correctly with App Router.

B2. Duplicate src/app/ path in file structure

File: Plan section "File Structure" (line 37-82 of memo)

The file structure lists src/app/sitemap.ts and src/app/robots.ts outside the main src/app/ tree (at the bottom, under src/lib/). This is confusing but not technically wrong since they would be in the same directory. However, the src/lib/sitemap.ts helper is listed separately from src/app/sitemap.ts. The builder needs clarity: src/lib/sitemap.ts is listed in the structure but never referenced in any code sample. The sitemap code is entirely in src/app/sitemap.ts. Either remove src/lib/sitemap.ts from the file structure or define what it contains.

Fix: Remove src/lib/sitemap.ts from the file structure. The sitemap logic is self-contained in src/app/sitemap.ts.

B3. Missing "use client" boundary for tool components in Suspense

File: Plan section "Dynamic Route with SSG" (line 171-219 of memo)

Even after fixing B1, if tool components are client components ("use client"), the server component page needs to handle the client/server boundary correctly. The plan should specify that each tool's Component.tsx has "use client" at the top (it mentions this in the per-tool sections but should be explicit in the architecture section as a hard rule). If the server component dynamically imports a client component, this works in Next.js App Router, but the plan should document this pattern clearly for the builder.

Fix: Add an explicit note in the Architecture section: "All tool Component.tsx files MUST have 'use client' as the first line. The [slug]/page.tsx server component dynamically imports these client components."

B4. MD5 implementation lacks specification

File: Plan section "Step 10: Hash Generator" (line 455-457 of memo)

The plan acknowledges MD5 is not in Web Crypto API and suggests "a small inline implementation (~50 lines)" but does not specify which implementation or provide a reference. This is ambiguous for the builder. The builder needs a concrete decision: include MD5 or not, and if yes, which specific implementation to use.

Fix: Either (a) specify a concrete MD5 implementation (e.g., link to a specific public domain algorithm or provide the code inline), or (b) explicitly decide to exclude MD5 and only support SHA-1, SHA-256, SHA-384, SHA-512 via Web Crypto API. Recommendation: exclude MD5 in Phase 1 to minimize risk and add it in a follow-up. The tool name can still be "Hash Generator" without MD5.

Non-Blocking Issues (Recommended)

NB1. index.ts re-export files are unnecessary

File: Plan section "File Structure", src/tools/[tool-slug]/index.ts

The file structure includes index.ts in each tool directory for "clean imports", but the registry imports directly from ./char-count/meta and ./char-count/Component. The index.ts files are never referenced in any code sample and add maintenance overhead for no benefit. If the builder creates these, they would be dead code.

Recommendation: Remove index.ts from the file structure, or specify what it re-exports and where it is used.

NB2. ToolDefinition type carries Component but registry access pattern does not need it

File: Plan section "Tool Registry Pattern", types.ts

ToolDefinition has Component: React.ComponentType, but after fixing B1, the registry would store the import function instead. The type should be updated to match the actual pattern (either componentImport function or the resolved component type).

Recommendation: Update ToolDefinition to match the chosen import pattern from B1.

NB3. No error boundary specified for tool components

Individual tool components are client-side and could throw errors (e.g., invalid input to regex, unexpected edge cases). The plan does not mention React Error Boundaries.

Recommendation: Add an ErrorBoundary component that wraps each tool in ToolLayout or [slug]/page.tsx, displaying a user-friendly error message instead of a blank page. This also satisfies Constitution Rule 2 (helpful experience).

NB4. Regex Tester timeout mechanism is vague

File: Plan section "Step 13: Regex Tester" and "Risks" (line 471-473, 567)

The plan mentions "timeout protection" and suggests a web worker with 3-second timeout as one option. The builder needs a concrete decision. A Web Worker adds significant implementation complexity (separate file, message passing, bundling considerations with Next.js).

Recommendation: For Phase 1, use a simpler approach: limit input text length (e.g., 10,000 characters), limit match count (e.g., 1,000 matches), and wrap in try/catch. This avoids the Web Worker complexity while still providing reasonable protection. Specify this explicitly so the builder does not have to make the architectural decision.

NB5. NEXT_PUBLIC_BASE_URL fallback uses placeholder domain

File: Plan sections "SEO Helpers" and "Sitemap" (line 231, 308)

The fallback "https://yolo-web.example.com" would produce invalid canonical URLs and sitemap entries in development. This is fine for development but if accidentally deployed without the env var, it would hurt SEO.

Recommendation: Add a note that the builder should log a warning when the fallback is used, or make the build fail if NEXT_PUBLIC_BASE_URL is not set in production mode.

NB6. Test strategy should specify component test approach

The plan specifies unit tests for logic.ts files (good), but does not describe how shared components (ToolLayout, AiDisclaimer, ToolsGrid, etc.) should be tested. The existing test setup uses @testing-library/react, which is appropriate for component tests.

Recommendation: Add explicit acceptance criteria: "Shared components (AiDisclaimer, ToolLayout, ToolCard, ToolsGrid) have at least smoke render tests." The AiDisclaimer component is constitution-critical and must be tested to confirm the disclaimer text renders.

NB7. No accessibility considerations mentioned

The plan covers SEO extensively but does not mention ARIA labels, keyboard navigation, focus management, or screen reader compatibility for the interactive tools. While not a constitution requirement, it affects the "helpful for visitors" criterion (Rule 2).

Recommendation: Add a brief note that tool components should use semantic HTML (<label>, <textarea>, <button>, <output>) and appropriate ARIA attributes. This is low-effort when built from the start.

Consistency with Existing Project Files

• package.json: React 19.2.4 and Next.js 16.1.6 are confirmed. The plan's use of App Router, generateStaticParams, and generateMetadata is compatible. The params as Promise pattern (line 188-189, 199-200) is correct for Next.js 15+/16.
• tsconfig.json: strict: true is confirmed. Path alias @/* maps to ./src/* -- matches the plan's import paths. target: ES2017 supports all referenced APIs except Intl.Segmenter (which is a runtime API, not a compile target issue, so this is fine).
• eslint.config.mjs: Uses eslint-config-next with Core Web Vitals and TypeScript rules. No conflicts with the plan.
• vitest.config.mts: Uses jsdom environment and @testing-library/react. Compatible with the plan's test approach for logic.ts unit tests. Note: testing components that use "use client" in vitest/jsdom may need additional setup -- the builder should be aware of this.
• globals.css: Currently minimal. The plan's CSS custom properties extension is compatible.

Summary of Required Actions

Before sending to builder, the planner must address:

1. [B1] Replace React.lazy with next/dynamic or await import() in the registry/page pattern
2. [B2] Remove src/lib/sitemap.ts from the file structure (dead reference)
3. [B3] Add explicit architecture note about "use client" boundary requirement
4. [B4] Make a concrete decision on MD5 (include with specified implementation, or exclude from Phase 1)

Recommended improvements (can be addressed during build):

5. [NB1] Remove unnecessary index.ts files from structure
6. [NB2] Update ToolDefinition type to match corrected import pattern
7. [NB3] Add error boundary for tool components
8. [NB4] Specify concrete regex timeout approach (input limits + try/catch)
9. [NB5] Add NEXT_PUBLIC_BASE_URL validation/warning
10. [NB6] Add component test expectations to acceptance criteria
11. [NB7] Add brief accessibility note

Next Actions

• Planner addresses the 4 blocking issues (B1-B4) -- either via a revised plan memo or a short errata memo
• Once blocking issues are resolved, project manager can approve and send to builder
• Non-blocking items (NB1-NB7) can be included in the builder's implementation memo as guidance