@squadbase/vantage-template 0.0.1 → 0.0.2-dev.7c29258

package/dist/index.js

@@ -4,12 +4,12 @@
 import { parseArgs } from "util";
 
 // src/commands/add.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { join as join5 } from "path";
 
 // src/ai/customize.ts
 import { readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join as join2 } from "path";
 
 // src/logger.ts
 var colors = {
@@ -24,6 +24,35 @@ function log(color, message) {
   console.log(`${colors[color]}${message}${colors.reset}`);
 }
 
+// src/project.ts
+import { existsSync } from "fs";
+import { join } from "path";
+var ROOT_LAYOUT_MARKERS = ["index.tsx", "_layout.tsx", "_404.tsx", "_error.tsx", "styles.css"];
+var AUTHORED_PAGE_PREFIX = "src/";
+function resolvePagePrefix(projectRoot) {
+  if (existsSync(join(projectRoot, "src"))) return AUTHORED_PAGE_PREFIX;
+  return findRootLayoutFiles(projectRoot).length > 0 ? "" : AUTHORED_PAGE_PREFIX;
+}
+function resolvePageRoot(projectRoot) {
+  return join(projectRoot, resolvePagePrefix(projectRoot));
+}
+function resolveStylesPath(projectRoot) {
+  return join(resolvePageRoot(projectRoot), "styles.css");
+}
+function resolveDest(entry, pagePrefix) {
+  return entry.scope === "root" ? entry.dest : pagePrefix + entry.dest;
+}
+function authoredDest(entry) {
+  return resolveDest(entry, AUTHORED_PAGE_PREFIX);
+}
+function findRootLayoutFiles(projectRoot) {
+  return ROOT_LAYOUT_MARKERS.filter((name) => existsSync(join(projectRoot, name)));
+}
+function findSplitLayoutFiles(projectRoot) {
+  if (!existsSync(join(projectRoot, "src"))) return [];
+  return findRootLayoutFiles(projectRoot);
+}
+
 // src/ai/diff.ts
 var ANSI = {
   reset: "\x1B[0m",
@@ -300,12 +329,13 @@ function buildUserPrompt(intent, files) {
   parts.push(`</FILES_TO_CUSTOMIZE>`);
   return parts.join("\n");
 }
-function readInputFiles(projectRoot, templateDir, entries, fromTemplate) {
+function readInputFiles(projectRoot, templateDir, entries, pagePrefix, fromTemplate) {
   const files = /* @__PURE__ */ new Map();
   for (const entry of entries) {
-    const path = fromTemplate ? join(templateDir, entry.src) : join(projectRoot, entry.dest);
+    const dest = resolveDest(entry, pagePrefix);
+    const path = fromTemplate ? join2(templateDir, entry.src) : join2(projectRoot, dest);
     try {
-      files.set(entry.dest, readFileSync(path, "utf-8"));
+      files.set(dest, readFileSync(path, "utf-8"));
     } catch (err) {
       throw new Error(
         `Failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`
@@ -400,13 +430,14 @@ ${snippet}`);
   if (e.usage) parts.push(`Usage: ${JSON.stringify(e.usage)}`);
   return parts.join("\n");
 }
-async function customizeWithAI(projectRoot, manifest, templateDir, options) {
+async function customizeWithAI(projectRoot, manifest, templateDir, options, pagePrefix) {
   const relabelFiles = manifest.files.filter((f) => f.relabel !== false);
-  const allowedPaths = relabelFiles.map((f) => f.dest);
+  const allowedPaths = relabelFiles.map((f) => resolveDest(f, pagePrefix));
   const inputFiles = readInputFiles(
     projectRoot,
     templateDir,
     relabelFiles,
+    pagePrefix,
     options.dryRun
   );
   if (!options.json) {
@@ -515,7 +546,7 @@ ${edit.path}  (+${edit.added} -${edit.removed})`);
     }
   } else {
     for (const edit of edits) {
-      writeFileSync(join(projectRoot, edit.path), edit.after, "utf-8");
+      writeFileSync(join2(projectRoot, edit.path), edit.after, "utf-8");
       if (!options.json) {
         log("cyan", `  rewrote: ${edit.path} (+${edit.added} -${edit.removed})`);
       }
@@ -584,34 +615,34 @@ function parseEditsString(raw) {
 }
 
 // src/apply.ts
-import { copyFileSync, existsSync as existsSync2, mkdirSync } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
+import { copyFileSync, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join4, posix } from "path";
 
 // src/manifest.ts
-import { existsSync, readFileSync as readFileSync2, readdirSync } from "fs";
-import { dirname, join as join2 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync } from "fs";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 function getTemplatesDir(source = "ui-templates") {
-  return join2(__dirname, "..", source);
+  return join3(__dirname, "..", source);
 }
 function getTemplateDir(templateName, source = "ui-templates") {
-  return join2(getTemplatesDir(source), templateName);
+  return join3(getTemplatesDir(source), templateName);
 }
 function listTemplateNames(source = "ui-templates") {
   const templatesDir = getTemplatesDir(source);
-  if (!existsSync(templatesDir)) {
+  if (!existsSync2(templatesDir)) {
     return [];
   }
   return readdirSync(templatesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
 }
 function loadManifest(templateName, source = "ui-templates") {
   const templateDir = getTemplateDir(templateName, source);
-  if (!existsSync(templateDir)) {
+  if (!existsSync2(templateDir)) {
     throw new Error(`Template "${templateName}" not found.`);
   }
-  const manifestPath = join2(templateDir, "manifest.json");
-  if (!existsSync(manifestPath)) {
+  const manifestPath = join3(templateDir, "manifest.json");
+  if (!existsSync2(manifestPath)) {
     throw new Error(`Template "${templateName}" is missing manifest.json.`);
   }
   const raw = JSON.parse(readFileSync2(manifestPath, "utf-8"));
@@ -624,7 +655,8 @@ function loadManifest(templateName, source = "ui-templates") {
 // src/apply.ts
 function applyTemplate(projectRoot, manifest, options) {
   const templateDir = getTemplateDir(manifest.name, options.source ?? "ui-templates");
-  const conflicts = checkConflicts(projectRoot, manifest.files, options.force);
+  const pagePrefix = resolvePagePrefix(projectRoot);
+  const conflicts = checkConflicts(projectRoot, manifest.files, pagePrefix, options.force);
   if (conflicts.length > 0) {
     log("red", "File conflicts detected (use --force to overwrite):");
     for (const c of conflicts) {
@@ -633,36 +665,77 @@ function applyTemplate(projectRoot, manifest, options) {
     process.exit(1);
   }
   for (const file of manifest.files) {
-    const src = join3(templateDir, file.src);
-    const dest = join3(projectRoot, file.dest);
+    const src = join4(templateDir, file.src);
+    const destRel = resolveDest(file, pagePrefix);
+    const dest = join4(projectRoot, destRel);
     if (options.dryRun) {
       const label2 = file.action === "replace" ? "replace" : "add";
-      log("dim", `  [dry-run] ${label2}: ${file.dest}`);
+      log("dim", `  [dry-run] ${label2}: ${destRel}`);
       continue;
     }
     mkdirSync(dirname2(dest), { recursive: true });
-    copyFileSync(src, dest);
+    const authored = isRewritable(file.src) ? readFileSync3(src, "utf-8") : null;
+    const retargeted = authored === null ? null : retargetRelativeImports(authored, file, pagePrefix);
+    if (retargeted === null) {
+      copyFileSync(src, dest);
+    } else {
+      writeFileSync2(dest, retargeted, "utf-8");
+    }
     const label = file.action === "replace" ? "replaced" : "added";
-    log("cyan", `  ${label}: ${file.dest}`);
+    const note = retargeted !== null && retargeted !== authored ? " (imports retargeted)" : "";
+    log("cyan", `  ${label}: ${destRel}${note}`);
   }
 }
-function checkConflicts(projectRoot, files, force) {
+function checkConflicts(projectRoot, files, pagePrefix, force) {
   if (force) return [];
-  return files.filter((f) => f.action === "add" && existsSync2(join3(projectRoot, f.dest))).map((f) => f.dest);
+  return files.filter((f) => f.action === "add").map((f) => resolveDest(f, pagePrefix)).filter((dest) => existsSync3(join4(projectRoot, dest)));
+}
+var REWRITABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cts", ".cjs"];
+function isRewritable(srcPath) {
+  return REWRITABLE_EXTENSIONS.some((ext) => srcPath.endsWith(ext));
+}
+var RELATIVE_SPECIFIER = /(\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)(["'])(\.{1,2}\/[^"']*)\2/g;
+function retargetRelativeImports(source, entry, pagePrefix) {
+  if (pagePrefix === AUTHORED_PAGE_PREFIX) return source;
+  const fromAuthored = posix.dirname(authoredDest(entry));
+  const fromActual = posix.dirname(resolveDest(entry, pagePrefix));
+  return source.replace(RELATIVE_SPECIFIER, (match, head, quote, spec) => {
+    const authoredTarget = posix.normalize(posix.join(fromAuthored, spec));
+    const actualTarget = retargetPath(authoredTarget, pagePrefix);
+    if (actualTarget === authoredTarget && fromActual === fromAuthored) return match;
+    let next = posix.relative(fromActual, actualTarget);
+    if (!next.startsWith(".")) next = `./${next}`;
+    return `${head}${quote}${next}${quote}`;
+  });
+}
+function retargetPath(authoredPath, pagePrefix) {
+  if (!authoredPath.startsWith(AUTHORED_PAGE_PREFIX)) return authoredPath;
+  return pagePrefix + authoredPath.slice(AUTHORED_PAGE_PREFIX.length);
 }
 
 // src/commands/add.ts
 function isVantageProject(projectRoot) {
-  const pkgPath = join4(projectRoot, "package.json");
-  if (!existsSync3(pkgPath)) return false;
+  const pkgPath = join5(projectRoot, "package.json");
+  if (!existsSync4(pkgPath)) return false;
   try {
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     return Boolean(pkg.dependencies?.["@squadbase/vantage"] ?? pkg.devDependencies?.["@squadbase/vantage"]);
   } catch {
     return false;
   }
 }
-function findStaleTemplateFiles(projectRoot, appliedTemplate, source) {
+function refuseSplitLayout(projectRoot) {
+  const rootPages = findSplitLayoutFiles(projectRoot);
+  if (rootPages.length === 0) return;
+  log("red", "This project has pages both in src/ and at the project root.");
+  log("yellow", "  Vantage scans only src/ once it exists. Move these into src/, then re-run:");
+  for (const name of rootPages) log("dim", `    ${name}`);
+  log("dim", "  Any components/ hooks/ lib/ directories holding page code move with them.");
+  log("dim", "  server/ and public/ stay at the project root.");
+  log("dim", "  Leaving both sides in place fails `vantage check` with SRC_DIR_SPLIT.");
+  process.exit(1);
+}
+function findStaleTemplateFiles(projectRoot, appliedTemplate, source, pagePrefix) {
   const stale = [];
   for (const name of listTemplateNames(source)) {
     if (name === appliedTemplate) continue;
@@ -675,7 +748,8 @@ function findStaleTemplateFiles(projectRoot, appliedTemplate, source) {
     }
     for (const file of manifest.files) {
       if (file.action !== "add") continue;
-      if (existsSync3(join4(projectRoot, file.dest))) stale.push(file.dest);
+      const dest = resolveDest(file, pagePrefix);
+      if (existsSync4(join5(projectRoot, dest))) stale.push(dest);
     }
   }
   return [...new Set(stale)].sort();
@@ -688,6 +762,8 @@ async function addTemplate(templateName, options) {
     log("dim", "Run 'npx @squadbase/vantage-template init' first.");
     process.exit(1);
   }
+  refuseSplitLayout(projectRoot);
+  const pagePrefix = resolvePagePrefix(projectRoot);
   const available = listTemplateNames(source);
   if (!available.includes(templateName)) {
     log("red", `Template "${templateName}" not found in ${source}/.`);
@@ -704,13 +780,14 @@ async function addTemplate(templateName, options) {
       log("yellow", "(dry run \u2014 no files will be changed)");
     }
     const entry = manifest.files.find((f) => f.action === "replace");
-    if (entry && existsSync3(join4(projectRoot, entry.dest))) {
-      log("yellow", `  ${entry.dest} will be overwritten \u2014 commit first if it holds your work.`);
+    const entryDest = entry ? resolveDest(entry, pagePrefix) : void 0;
+    if (entryDest && existsSync4(join5(projectRoot, entryDest))) {
+      log("yellow", `  ${entryDest} will be overwritten \u2014 commit first if it holds your work.`);
     }
   }
   applyTemplate(projectRoot, manifest, options);
   if (!options.ai?.json) {
-    const stale = findStaleTemplateFiles(projectRoot, templateName, source);
+    const stale = findStaleTemplateFiles(projectRoot, templateName, source, pagePrefix);
     if (stale.length > 0) {
       log("yellow", "\nLeftovers from a previously applied template (nothing imports them):");
       for (const dest of stale) log("dim", `  ${dest}`);
@@ -718,7 +795,13 @@ async function addTemplate(templateName, options) {
     }
   }
   if (options.ai) {
-    const result = await customizeWithAI(projectRoot, manifest, templateDir, options.ai);
+    const result = await customizeWithAI(
+      projectRoot,
+      manifest,
+      templateDir,
+      options.ai,
+      pagePrefix
+    );
     if (options.ai.json) {
       console.log(
         JSON.stringify(
@@ -777,12 +860,12 @@ Run "git diff" to review the AI changes.`);
 }
 
 // src/commands/chart.ts
-import { existsSync as existsSync5 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { relative as relative2 } from "path";
 
 // src/chart-presets.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join6, relative } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
 var PRESET_DESCRIPTIONS = {
@@ -796,34 +879,34 @@ var PRESET_DESCRIPTIONS = {
 var BEGIN_MARKER = "/* vantage-template:chart-preset \u2014 regenerated by `chart`; edits here are lost */";
 var END_MARKER = "/* vantage-template:chart-preset:end */";
 function getChartPresetsDir() {
-  return join5(__dirname2, "..", "chart-presets");
+  return join6(__dirname2, "..", "chart-presets");
 }
 function listChartPresetNames() {
   const dir = getChartPresetsDir();
-  if (!existsSync4(dir)) return [];
+  if (!existsSync5(dir)) return [];
   return readdirSync2(dir).filter((f) => f.endsWith(".css")).map((f) => f.replace(/\.css$/, "")).sort();
 }
 function getChartPresetDescription(name) {
   return PRESET_DESCRIPTIONS[name] ?? "";
 }
 function getChartPresetPath(name) {
-  return join5(getChartPresetsDir(), `${name}.css`);
+  return join6(getChartPresetsDir(), `${name}.css`);
 }
 function applyChartPreset(projectRoot, presetName, options = {}) {
   const presetPath = getChartPresetPath(presetName);
-  if (!existsSync4(presetPath)) {
+  if (!existsSync5(presetPath)) {
     throw new Error(`Chart preset "${presetName}" not found.`);
   }
-  const targetPath = join5(projectRoot, "styles.css");
-  if (!existsSync4(targetPath)) {
-    throw new Error("styles.css not found in project.");
+  const targetPath = resolveStylesPath(projectRoot);
+  if (!existsSync5(targetPath)) {
+    throw new Error(`${relative(projectRoot, targetPath)} not found in project.`);
   }
-  const preset = readFileSync4(presetPath, "utf-8").trimEnd();
+  const preset = readFileSync5(presetPath, "utf-8").trimEnd();
   const block = `${BEGIN_MARKER}
 ${preset}
 ${END_MARKER}
 `;
-  const current = readFileSync4(targetPath, "utf-8");
+  const current = readFileSync5(targetPath, "utf-8");
   const begin = current.indexOf(BEGIN_MARKER);
   const end = current.indexOf(END_MARKER);
   let content;
@@ -835,7 +918,7 @@ ${END_MARKER}
 ${block}`;
   }
   if (!options.dryRun) {
-    writeFileSync2(targetPath, content, "utf-8");
+    writeFileSync3(targetPath, content, "utf-8");
   }
   return { targetPath, content };
 }
@@ -843,9 +926,10 @@ ${block}`;
 // src/commands/chart.ts
 function setChartPreset(presetName, options) {
   const projectRoot = process.cwd();
-  const stylesPath = join6(projectRoot, "styles.css");
-  if (!existsSync5(stylesPath)) {
-    log("red", "styles.css not found. Are you in a Squadbase Vantage project?");
+  const stylesPath = resolveStylesPath(projectRoot);
+  const stylesLabel = relative2(projectRoot, stylesPath);
+  if (!existsSync6(stylesPath)) {
+    log("red", `${stylesLabel} not found. Are you in a Squadbase Vantage project?`);
     process.exit(1);
   }
   const available = listChartPresetNames();
@@ -864,18 +948,19 @@ function setChartPreset(presetName, options) {
   if (options.dryRun) {
     log("yellow", "(dry run \u2014 no files will be changed)");
     const { content } = applyChartPreset(projectRoot, presetName, { dryRun: true });
-    log("dim", "\n--- styles.css (preview) ---");
+    log("dim", `
+--- ${stylesLabel} (preview) ---`);
     console.log(content);
     return;
   }
   applyChartPreset(projectRoot, presetName);
-  log("cyan", "  updated: styles.css");
+  log("cyan", `  updated: ${stylesLabel}`);
   log("green", "\nChart preset applied successfully!");
 }
 
 // src/commands/init.ts
 import { spawnSync } from "child_process";
-import { cpSync, existsSync as existsSync6, mkdirSync as mkdirSync2, readdirSync as readdirSync3 } from "fs";
+import { cpSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readdirSync as readdirSync3 } from "fs";
 import { dirname as dirname4, join as join7 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var __dirname3 = dirname4(fileURLToPath3(import.meta.url));
@@ -888,7 +973,7 @@ function getBaseTemplateDir() {
 function initProject(options) {
   const targetDir = process.cwd();
   const baseTemplateDir = getBaseTemplateDir();
-  if (!existsSync6(baseTemplateDir)) {
+  if (!existsSync7(baseTemplateDir)) {
     log("red", "Base template not found. The package may be corrupted.");
     process.exit(1);
   }
@@ -902,13 +987,16 @@ function initProject(options) {
       process.exit(1);
     }
   }
-  if (!options.force && existsSync6(join7(targetDir, "squadbase.yml"))) {
+  if (!options.force && existsSync7(join7(targetDir, "squadbase.yml"))) {
     log("red", "This directory already contains a Squadbase project (squadbase.yml exists).");
     log("yellow", "Use --force to overwrite.");
     process.exit(1);
   }
-  if (!options.force && existsSync6(join7(targetDir, "index.tsx"))) {
-    log("red", "This directory already contains an index.tsx.");
+  const existingEntry = ["src/index.tsx", "index.tsx"].find(
+    (rel) => existsSync7(join7(targetDir, rel))
+  );
+  if (!options.force && existingEntry) {
+    log("red", `This directory already contains a ${existingEntry}.`);
     log("yellow", "Use --force to overwrite.");
     process.exit(1);
   }
@@ -922,7 +1010,7 @@ function initProject(options) {
       mkdirSync2(dest, { recursive: true });
       cpSync(src, dest, { recursive: true, force: options.force });
     } else {
-      if (!options.force && existsSync6(dest)) {
+      if (!options.force && existsSync7(dest)) {
         log("yellow", `  skipped (exists): ${destName}`);
         continue;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage-template",
-  "version": "0.0.1",
+  "version": "0.0.2-dev.7c29258",
   "description": "CLI tool for initializing and customizing Squadbase Vantage projects.",
   "keywords": [
     "squadbase",
@@ -12,12 +12,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/squadbase/squadbase-templates.git",
-    "directory": "vantage-template"
+    "url": "git+https://github.com/squadbase/squadbase-monorepo.git",
+    "directory": "packages/vantage-template"
   },
-  "homepage": "https://github.com/squadbase/squadbase-templates/tree/main/vantage-template#readme",
+  "homepage": "https://github.com/squadbase/squadbase-monorepo/tree/main/packages/vantage-template#readme",
   "bugs": {
-    "url": "https://github.com/squadbase/squadbase-templates/issues"
+    "url": "https://github.com/squadbase/squadbase-monorepo/issues"
   },
   "type": "module",
   "engines": {
@@ -33,16 +33,25 @@
     "chart-presets"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "sync-base": "rsync -a --delete --exclude='node_modules' --exclude='dist' --exclude='.vantage' --exclude='package-lock.json' --exclude='*.tsbuildinfo' --exclude='*.log' ../vantage/ base-template/ && mv base-template/.gitignore base-template/_gitignore",
+    "sync-base": "rsync -a --delete --exclude='node_modules' --exclude='dist' --exclude='.vantage' --exclude='package-lock.json' --exclude='*.tsbuildinfo' --exclude='*.log' template/ base-template/ && mv base-template/.gitignore base-template/_gitignore",
     "build": "npm run sync-base && tsup",
-    "prepublishOnly": "npm run build",
-    "release": "npm publish --@squadbase:registry=https://registry.npmjs.org"
+    "type-check": "tsc",
+    "agents": "node scripts/build-agents.cjs",
+    "agents:check": "node scripts/build-agents.cjs --check",
+    "template:install": "npm --prefix template ci",
+    "template:build": "npm --prefix template run build",
+    "prepublishOnly": "npm run agents:check && npm run build",
+    "release": "npm publish --@squadbase:registry=https://registry.npmjs.org",
+    "dev": "node scripts/dev.mjs",
+    "screenshot": "node scripts/screenshot.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",
+    "playwright": "^1.49.0",
     "tsup": "^8.4.0",
     "typescript": "~5.7.0"
   },

package/ui-templates/CLAUDE.md

@@ -6,7 +6,7 @@ UIパターン別テンプレート（KPI重視・チャート格子・テーブ
 
 このファイルは `vantage-template/ui-templates/` 配下のファイル構成ルールを定義する。デザイン要件・AI relabel・EN/JA・CLI の挙動は親 [`../CLAUDE.md`](../CLAUDE.md) に従う。
 
-> **Vite 版との差分**: 適用先が Vantage アプリ（`@squadbase/vantage`）になったため、(1) エントリは `src/pages/home.tsx` ではなく **ルートの `index.tsx`**、(2) テンプレ固有ファイルは `src/templates/<slug>/` ではなく **`components/<slug>/`**、(3) 全ての building block を `@squadbase/vantage/*` から import する（ローカルコピーは持たない）。
+> **Vite 版との差分**: 適用先が Vantage アプリ（`@squadbase/vantage`）になったため、(1) エントリは `src/pages/home.tsx` ではなく **`src/index.tsx`**、(2) テンプレ固有ファイルは `src/templates/<slug>/` ではなく **`src/components/<slug>/`**、(3) 全ての building block を `@squadbase/vantage/*` から import する（ローカルコピーは持たない）。
 
 ## 設計目標
 
@@ -20,21 +20,25 @@ UIパターン別テンプレート（KPI重視・チャート格子・テーブ
 
 ### 1. 1テンプレ = 1ディレクトリ（コロケーション）
 
-適用先では、`index.tsx`（エントリ）以外のテンプレ固有ファイルを **`components/<slug>/` 1ディレクトリに集約** する。
+適用先では、`src/index.tsx`（エントリ）以外のテンプレ固有ファイルを **`src/components/<slug>/` 1ディレクトリに集約** する。
 
 ```
 # 適用先（dest）レイアウト
-index.tsx                             # エントリ（ルート "/"）
-components/<slug>/
+src/index.tsx                         # エントリ（ルート "/"）
+src/components/<slug>/
   mock-data.ts                        # データ層（relabel:false / 差し替え対象）
   types.ts                            # 型（index と data で共有）
   ...（分割した場合のみ追加ファイル）
 ```
 
-- **探索**: `components/<slug>/` を見ればテンプレ由来が一覧完結
-- **削除**: `rm -rf components/<slug>/` で一掃
+- **探索**: `src/components/<slug>/` を見ればテンプレ由来が一覧完結
+- **削除**: `rm -rf src/components/<slug>/` で一掃
 
-**`components/` を使う理由（重要）**: Vantage は**ファイルベースルーティング**で、`.tsx` ファイルは原則すべてページ扱いになる。`components/` / `hooks/` / `lib/` / `server/` / `public/` だけがルート走査から除外される（`NON_ROUTE_DIRS`）ため、`templates/<slug>/` のようなディレクトリに `.tsx` を置くと **`/templates/<slug>/...` という意図しないルートが生え、`vantage check` が `MISSING_DEFAULT_EXPORT` で落ちる**。データファイル（`.ts`）も同じディレクトリに置いてコロケーションを保つ。
+**`src/` を使う理由（v0.3.0 以降）**: ページ探索ルートは `src/` の有無だけで決まる。ベーステンプレートは `src/` を持つので、ページとそれが import するものは**すべて `src/` の中**に置く。`src/` があるのにルート直下に `.tsx` や `styles.css` を残すと `vantage check` が `SRC_DIR_SPLIT` エラーにする。**例外は `server/` と `public/` で、これらは常にプロジェクトルート直下**（`src/server/` はスキャンされない）。
+
+**ただし manifest の `dest` に `src/` は書かない。** `dest` は**ページ探索ルート相対**（`index.tsx` / `components/<slug>/x.tsx`）で、`src/` を付けるかどうかは適用先のレイアウトを見て CLI が決める（ルート直下にページを置くプロジェクトにも適用できる）。`server/` `public/` だけ `"scope": "root"` を付けてプロジェクトルート固定にする。オーサリング側のファイルは**常に `src/` レイアウト前提**で書き、`src/` を跨ぐ相対 import は適用時に CLI が張り替える。
+
+**`components/` を使う理由（重要）**: Vantage は**ファイルベースルーティング**で、`.tsx` ファイルは原則すべてページ扱いになる。`components/` / `hooks/` / `lib/` / `server/` / `public/` だけがルート走査から除外される（`NON_ROUTE_DIRS`）ため、`src/templates/<slug>/` のようなディレクトリに `.tsx` を置くと **`/templates/<slug>/...` という意図しないルートが生え、`vantage check` が `MISSING_DEFAULT_EXPORT` で落ちる**（`SUSPICIOUS_ROUTE_DIR` 警告も出る）。データファイル（`.ts`）も同じディレクトリに置いてコロケーションを保つ。
 
 ### 2. インライン優先 — 薄いラッパ component を作らない
 
@@ -55,20 +59,21 @@ function areaOption(data: TimePoint[]): EChartsOption {
 
 ### 3. データ層（mock-data / types）は分離する
 
-`mock-data.ts` と `types.ts` は `index.tsx` に inline せず、`components/<slug>/` の別ファイルに保つ。表示ラベル（KPI名・軸名・stage名など）は描画側（`index.tsx`）の literal/const に置き、データ配列には値・id・generic な sample text のみ置く。
+`mock-data.ts` と `types.ts` は `src/index.tsx` に inline せず、`src/components/<slug>/` の別ファイルに保つ。表示ラベル（KPI名・軸名・stage名など）は描画側（`index.tsx`）の literal/const に置き、データ配列には値・id・generic な sample text のみ置く。
 
 ### 3-b. API 版テンプレ（`server/api` から配信する場合）
 
-`kpi-chart-simple` はモック配列を直読みせず、**`server/api` から `useApiQuery` で取る**構成になっている。実データ接続までの導線を1本コードで示すためのもので、この構成を採るテンプレは dest の置き場が変わる:
+`kpi-chart-simple` はモック配列を直読みせず、**`server/api` から `useApiQuery` で取る**構成になっている。実データ接続までの導線を1本コードで示すためのもので、この構成を採るテンプレは置き場が変わる（以下は `src/` レイアウトに適用したときの実配置。manifest の `dest` は `src/` を除いた形で書く）:
 
 ```
-index.tsx                                # useApiQuery + useSearchParam
-components/<slug>/*.tsx                  # 表示コンポーネント
-lib/<slug>/types.ts                      # ★ client と server が共有する型（relabel:false）
-server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハンドラ（relabel:false）
+src/index.tsx                            # useApiQuery + useSearchParam
+src/components/<slug>/*.tsx              # 表示コンポーネント
+src/lib/<slug>/types.ts                  # ★ client と server が共有する型（relabel:false）
+server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハンドラ（relabel:false）※ルート直下
 ```
 
-- **共有型は `components/` ではなく `lib/`** に置く。クライアントは `server/` を import できない（`CLIENT_IMPORTS_SERVER`）ので、両者が参照できる中立な場所が要る。`lib/` もルート走査対象外なので安全。
+- **共有型は `components/` ではなく `src/lib/`** に置く。クライアントは `server/` を import できない（`CLIENT_IMPORTS_SERVER`）ので、両者が参照できる中立な場所が要る。`lib/` もルート走査対象外なので安全。
+- **`server/` は `src/` の外**なので、ハンドラからの相対 import は `src/` を跨ぐ: `server/api/<endpoint>.ts` からは `../../src/lib/<slug>/types`。`src/components/<slug>/*.tsx` からは `../../lib/<slug>/types`（どちらも `src/` の中なので `src/` は出てこない）。
 - **サンプルデータはサーバー側に置く。** 「実装者が差し替える場所」がハンドラ1箇所に集約され、`KpiSummary` のような payload 型さえ保てばページを触らずに実データへ移行できる。
 - **絞り込みは `useSearchParam` + `useApiQuery` の `search`** で組む。`search` はクエリ文字列とキャッシュキーの両方に入るので、URL を変えれば再取得される。
 - クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。`useApiQuery` の `error` は `ApiError` なのでキャスト不要で `.message` が読める。
@@ -81,7 +86,7 @@ server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハ
 
 ### 分割してよい例外
 
-**再利用される** / **内部 state・interaction を持つ** / **`index.tsx` が 400〜500 行を超える** のいずれかに当てはまる UI のみ、`components/<slug>/` 配下に切り出してよい。迷ったら inline。
+**再利用される** / **内部 state・interaction を持つ** / **`index.tsx` が 400〜500 行を超える** のいずれかに当てはまる UI のみ、`src/components/<slug>/` 配下に切り出してよい。迷ったら inline。
 
 ## import 規約（Vantage）
 
@@ -101,11 +106,14 @@ server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハ
 **相対 import は拡張子なしで書く**（`@squadbase/vantage` v0.2.0 で `.js` 指定子の規約は廃止。既存の `.js` 付き import も動くが、新規テンプレでは付けない）。
 
 ```tsx
-// index.tsx から
+// src/index.tsx から
 import { MOCK_SERIES } from "./components/<slug>/mock-data"
 
-// components/<slug>/detail-table.tsx から
+// src/components/<slug>/detail-table.tsx から
 import type { Row } from "./types"
+
+// server/api/<endpoint>.ts から（src/ の外なので src/ を跨ぐ）
+import type { Payload } from "../../src/lib/<slug>/types"
 ```
 
 `Placeholder` / `Sparkline` はローカルコピーではなく `@squadbase/vantage/components` から取る（v0.1.1 でフレームワークに入った）。
@@ -123,7 +131,7 @@ Vantage の UI キットは Radix ではなく **Base UI** ベース。移植時
 
 ## エントリの必須要件
 
-`index.tsx` は **default export の React component** が必須（無いと `vantage check` が `MISSING_DEFAULT_EXPORT`）。加えてタイトル/説明を `definePage` で宣言する:
+`src/index.tsx` は **default export の React component** が必須（無いと `vantage check` が `MISSING_DEFAULT_EXPORT`）。加えてタイトル/説明を `definePage` で宣言する:
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
@@ -150,9 +158,11 @@ ui-templates/<slug>/
   lib/mock-data.ts      → dest: components/<slug>/mock-data.ts     (add, relabel:false)
   lib/types.ts          → dest: components/<slug>/types.ts         (add, relabel:false)
   components/*.tsx      → dest: components/<slug>/*.tsx            (add)  ※分割した場合のみ
-  server/*.ts           → dest: server/api/*.ts                    (add, relabel:false) ※API 版のみ
+  server/*.ts           → dest: server/api/*.ts, scope: "root"     (add, relabel:false) ※API 版のみ
 ```
 
+**オーサリング側のディレクトリ名（`pages/` `lib/` `components/` `server/`）は適用先の dest と一致しない。** dest だけが真実で、`manifest.json` に書く。**dest はページ探索ルート相対なので `src/` は付けない**（`scope: "root"` のものだけプロジェクトルート相対）。
+
 API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/types.ts` になり、`lib/mock-data.ts` は無く、代わりに `server/*.ts` を持つ。上の「3-b」を参照。
 
 ## manifest.json
@@ -172,6 +182,7 @@ API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/ty
 
 - `files[]` が manifest の全て（`nav[]` は無い）。ベーステンプレートのナビは `useRoutes()` からルート一覧を組むので、ページファイルをコピーすればナビにも載る
 - データファイルには `"relabel": false` を必ず付ける
+- `dest` に `src/` を書かない。`server/` `public/` にだけ `"scope": "root"` を付ける
 
 ## 見本市の例外ルール
 
@@ -189,7 +200,7 @@ API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/ty
 
 ## チェックリスト（テンプレ追加・改修時）
 
-1. テンプレ固有ファイルの `dest` は `components/<slug>/` 配下か（`templates/` に `.tsx` を置いていないか）
+1. テンプレ固有ファイルの `dest` は `components/<slug>/` 配下か（`templates/` に `.tsx` を置いていないか）。`dest` に `src/` を書いていないか。`server/*` だけ `dest: server/api/*` + `"scope": "root"` か
 2. `@/` エイリアスや `echarts` / `@tanstack/*` の直接 import、`Placeholder` / `Sparkline` のローカル import が残っていないか
 3. 相対 import に `.js` 拡張子が残っていないか（v0.2.0 で規約廃止）
 4. 薄いチャートラッパ component を作っていないか。チャートに色をハードコードしていないか（`option.color` / `itemStyle.color` / `theme`）
@@ -197,4 +208,4 @@ API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/ty
 6. 未使用の関数・型・import が残っていないか
 7. 適用先で `npx vantage check` と `npx tsc --noEmit` が通るか
 8. EN/JA 両方を同じ構成に揃えたか
-9. レイアウトを変えたなら `preview-wide.png` (1600x900) / `preview-square.png` (1200x1200) を撮り直したか
+9. レイアウトを変えたなら `preview-wide.png` (1600x900) / `preview-square.png` (1200x1200) を撮り直したか — `cd vantage-template && npm run screenshot <slug> <slug>-ja`（全部撮り直すなら引数なし）