stylegallery 0.1.10 → 0.1.12

package/scripts/pattern-data.mjs

@@ -323,3 +323,412 @@ export const patterns = [
   ["masonry-approx", "Grid / Repetition", "Approximate staggered content with columns when exact row alignment is not needed.", "block", "fluid", sources.mdnCookbook, [[".masonry_approx", { "column-gap": "1rem", "column-width": "14rem" }]]],
   ["main-with-rail", "Split / Sidebar", "Keep primary content dominant with a narrow secondary rail.", "inline", "reflow", sources.govukLayout, [[".main_with_rail", { display: "grid", gap: "1rem", "grid-template-columns": "repeat(auto-fit, minmax(min(18rem, 100%), 1fr))" }], [".main_with_rail_main", { "min-inline-size": "0" }], [".main_with_rail_side", { "min-inline-size": "0" }]]],
 ];
+
+// Search-only metadata: English and Korean names an agent may use for each pattern,
+// and questions the pattern's sections answer. Emitted as frontmatter aliases/questions.
+export const searchMetadata = {
+  "sticky-header": {
+    "aliases": [
+            "pinned top bar",
+      "sticky top navigation",
+      "헤더 고정",
+      "고정 헤더",
+      "상단 고정 메뉴"
+    ],
+    "questions": [
+      "How do I keep the header visible while the page scrolls?"
+    ]
+  },
+  "sticky-footer": {
+    "aliases": [
+      "footer at bottom",
+      "push footer down",
+      "푸터 고정",
+      "하단 푸터",
+      "푸터를 화면 아래에 붙이기"
+    ],
+    "questions": [
+      "How do I keep the footer at the bottom when content is short?"
+    ]
+  },
+  "scroll-body-shell": {
+    "aliases": [
+      "fixed header and footer with scrolling body",
+      "app shell",
+      "스크롤 영역",
+      "본문만 스크롤"
+    ],
+    "questions": [
+      "How do I make only the body scroll between a fixed header and footer?"
+    ]
+  },
+  "fixed-sidenav-shell": {
+    "aliases": [
+      "fixed side navigation",
+      "sidenav shell",
+      "고정 사이드 내비게이션",
+      "사이드바 레이아웃",
+      "고정 사이드바"
+    ],
+    "questions": [
+      "How do I keep side navigation fixed while the main content scrolls?"
+    ]
+  },
+  "holy-grail": {
+    "aliases": [
+      "header footer two sidebars",
+      "three column page layout",
+      "홀리 그레일 레이아웃",
+      "3단 레이아웃"
+    ],
+    "questions": [
+      "How do I lay out a header, footer, two sidebars, and main content?"
+    ]
+  },
+  "cover": {
+    "aliases": [
+      "full height hero",
+      "vertically centered hero",
+      "커버 레이아웃",
+      "전체 높이 히어로"
+    ]
+  },
+  "panel-layout": {
+    "aliases": [
+      "main and utility panels",
+      "패널 레이아웃"
+    ]
+  },
+  "sidebar": {
+    "aliases": [
+      "wrapping sidebar",
+      "intrinsic sidebar",
+      "사이드바",
+      "사이드바 레이아웃"
+    ],
+    "questions": [
+      "How do I make a sidebar wrap under the content when space is tight?"
+    ]
+  },
+  "sticky-aside": {
+    "aliases": [
+      "sticky sidebar",
+      "sticky table of contents",
+      "고정 사이드 영역",
+      "스티키 사이드바"
+    ],
+    "questions": [
+      "How do I keep an aside visible during long reads?"
+    ]
+  },
+  "switcher": {
+    "aliases": [
+      "row to stack without media query",
+      "flex switcher",
+      "가로 세로 전환"
+    ],
+    "questions": [
+      "How do I switch equal regions from a row to a stack without a breakpoint?"
+    ]
+  },
+  "list-detail": {
+    "aliases": [
+      "master detail",
+      "list and detail panes",
+      "목록 상세",
+      "리스트 디테일"
+    ]
+  },
+  "split-screen": {
+    "aliases": [
+      "two column split",
+      "50/50 split",
+      "화면 분할",
+      "2단 분할"
+    ]
+  },
+  "main-with-rail": {
+    "aliases": [
+      "content with right rail",
+      "secondary rail",
+      "메인과 보조 레일"
+    ]
+  },
+  "media-object": {
+    "aliases": [
+      "image beside text",
+      "avatar with text",
+      "미디어 오브젝트",
+      "이미지와 텍스트 나란히"
+    ]
+  },
+  "supporting-pane": {
+    "aliases": [
+      "supporting panel",
+      "보조 패널"
+    ]
+  },
+  "ram-grid": {
+    "aliases": [
+      "repeat auto-fit minmax",
+      "responsive grid without media queries",
+      "auto-fit grid",
+      "반응형 그리드",
+      "반응형 카드 그리드"
+    ],
+    "questions": [
+      "How do I make a grid that fits as many columns as space allows without media queries?"
+    ]
+  },
+  "card-grid": {
+    "aliases": [
+      "responsive card grid",
+      "cards in rows and columns",
+      "카드 그리드",
+      "반응형 카드 그리드",
+      "카드 목록"
+    ],
+    "questions": [
+      "How do I align repeating cards into a responsive grid?"
+    ]
+  },
+  "dense-grid": {
+    "aliases": [
+      "compact grid",
+      "grid-auto-flow dense",
+      "촘촘한 그리드"
+    ]
+  },
+  "twelve-span-grid": {
+    "aliases": [
+      "12 column grid",
+      "twelve column layout",
+      "12단 그리드"
+    ]
+  },
+  "page-grid": {
+    "aliases": [
+      "page margins and gutters",
+      "central content track",
+      "페이지 그리드"
+    ]
+  },
+  "grid-wrapper": {
+    "aliases": [
+      "full bleed breakout",
+      "full-width breakout",
+      "풀 블리드",
+      "전체 폭 확장"
+    ]
+  },
+  "columns": {
+    "aliases": [
+      "multi-column text",
+      "css columns",
+      "다단 텍스트"
+    ]
+  },
+  "masonry-approx": {
+    "aliases": [
+      "masonry",
+      "pinterest style",
+      "staggered layout",
+      "메이슨리",
+      "핀터레스트 스타일"
+    ]
+  },
+  "reel": {
+    "aliases": [
+      "horizontal scroll row",
+      "carousel row",
+      "scrollable row",
+      "가로 스크롤",
+      "가로 스크롤 목록"
+    ],
+    "questions": [
+      "How do I make a row scroll horizontally instead of wrapping?"
+    ]
+  },
+  "cluster": {
+    "aliases": [
+      "inline group that wraps",
+      "tag group",
+      "항목 묶음",
+      "줄바꿈 그룹"
+    ]
+  },
+  "breadcrumb": {
+    "aliases": [
+      "breadcrumbs",
+      "hierarchy links",
+      "브레드크럼",
+      "경로 표시"
+    ]
+  },
+  "pagination": {
+    "aliases": [
+      "page numbers",
+      "page controls",
+      "페이지네이션",
+      "페이지 번호"
+    ]
+  },
+  "tab-strip": {
+    "aliases": [
+      "tabs row",
+      "tab bar",
+      "탭 바",
+      "탭 메뉴"
+    ]
+  },
+  "split-nav": {
+    "aliases": [
+      "navbar with left and right items",
+      "primary and secondary nav",
+      "내비게이션 바",
+      "좌우 분리 내비게이션"
+    ]
+  },
+  "wrap-row": {
+    "aliases": [
+      "wrapping toolbar",
+      "button row that wraps",
+      "버튼 줄바꿈"
+    ]
+  },
+  "badge-list": {
+    "aliases": [
+      "tags with counts",
+      "labels with trailing counts",
+      "배지 목록",
+      "개수 표시 목록"
+    ]
+  },
+  "deconstructed-pancake": {
+    "aliases": [
+      "cards stretch then stack",
+      "flex wrap cards",
+      "카드 가로 배치 후 세로 쌓기"
+    ]
+  },
+  "stack": {
+    "aliases": [
+      "vertical rhythm",
+      "vertical spacing between children",
+      "스택",
+      "세로 간격"
+    ]
+  },
+  "feed": {
+    "aliases": [
+      "content feed",
+      "activity feed",
+      "피드"
+    ]
+  },
+  "line-up": {
+    "aliases": [
+      "equal height cards",
+      "buttons aligned at bottom",
+      "card footer alignment",
+      "카드 버튼 하단 정렬"
+    ],
+    "questions": [
+      "How do I align card footer actions at the bottom?"
+    ]
+  },
+  "step-nav": {
+    "aliases": [
+      "stepper",
+      "steps list",
+      "단계 표시",
+      "스텝 내비게이션"
+    ]
+  },
+  "center": {
+    "aliases": [
+      "center horizontally",
+      "max width centered",
+      "가운데 정렬",
+      "수평 가운데 정렬"
+    ]
+  },
+  "super-center": {
+    "aliases": [
+      "center horizontally and vertically",
+      "center a div",
+      "place-items center",
+      "가운데 정렬",
+      "정중앙 정렬"
+    ],
+    "questions": [
+      "How do I center an element both horizontally and vertically?"
+    ]
+  },
+  "box": {
+    "aliases": [
+      "padded box",
+      "내부 여백 박스"
+    ]
+  },
+  "clamped-card": {
+    "aliases": [
+      "card max width clamp",
+      "카드 폭 제한"
+    ]
+  },
+  "content-limiter": {
+    "aliases": [
+      "readable line length",
+      "max measure",
+      "prose width",
+      "읽기 좋은 줄 길이",
+      "본문 폭 제한"
+    ],
+    "questions": [
+      "How do I keep prose at a readable line length?"
+    ]
+  },
+  "fluid-styles": {
+    "aliases": [
+      "fluid width with max",
+      "유동 폭"
+    ]
+  },
+  "frame": {
+    "aliases": [
+      "aspect ratio box",
+      "responsive image slot",
+      "object-fit",
+      "이미지 비율 유지",
+      "종횡비"
+    ],
+    "questions": [
+      "How do I keep media at a fixed aspect ratio?"
+    ]
+  },
+  "icon-frame": {
+    "aliases": [
+      "icon slot",
+      "square icon box",
+      "아이콘 정렬"
+    ]
+  },
+  "imposter": {
+    "aliases": [
+      "overlay over parent",
+      "positioned overlay",
+      "modal over card",
+      "오버레이",
+      "겹쳐 띄우기"
+    ]
+  },
+  "overlay-stack": {
+    "aliases": [
+      "stack in one grid cell",
+      "text over image",
+      "겹치는 레이어",
+      "이미지 위 텍스트"
+    ]
+  }
+};

package/scripts/sg-entry.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 try {
-  const { runSgCli } = await import("./compiler/cli.mjs");
+  const { runStylegalleryCli } = await import("./stylegallery-cli.mjs");
   const controller = new AbortController();
   const cancel = () => controller.abort();
   process.once("SIGINT", cancel);
   process.once("SIGTERM", cancel);
   try {
-    const result = await runSgCli(process.argv.slice(2), { signal: controller.signal });
+    const result = await runStylegalleryCli(process.argv.slice(2), { signal: controller.signal });
     process.stdout.write(result.output);
     process.exitCode = result.exitCode;
   } finally {

package/scripts/sg-material-mcp.mjs

@@ -54,7 +54,7 @@ export class MaterialMcpStdin extends Transform {
   }
 }
 
-async function main() {
+export async function main() {
   const server = createMaterialMcpServer();
   const input = new MaterialMcpStdin();
   const transport = new StdioServerTransport(input);

package/scripts/stylegallery-cli.mjs

@@ -0,0 +1,130 @@
+// The single `stylegallery` command. search/read use search v3; context with
+// --query uses material v2; retrieve uses the v1 registry; every other command
+// (discover, resolve, claims, context <ref>, ops, registrar, conservator,
+// compiler stages) goes to the existing governed CLI unchanged.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function packageVersion() {
+  return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+}
+
+export const HELP_TEXT = `stylegallery - search and read the StyleGallery knowledge corpus, plus governed records and site compilation.
+
+Usage: stylegallery <command> [options]
+
+Find and read documents (offline, deterministic):
+  search <query...>             Rank documents; prints JSON (schema 3.0).
+      --query-en <text>         English rewrite of a non-English query. Agents: always pass one for Korean queries.
+      --limit <n>               Results to return, 1-50 (default 5).
+      --paths-only              Print repository-relative paths only.
+      --detailed                Add scores, hash identities, and ranking terms.
+  read <id|path>                Read one document by id (sg:layout/sticky-header), path, or StableRef.
+      --outline                 List headings with section slugs instead of the content.
+      --section <slug>          Read one section only.
+  context --query <text>        Build a bounded, provenance-linked material context package.
+      --budget-tokens <n>       Token budget, 256-32768 (default 8192).
+
+Governed records:
+  discover                      List interfaces, domains, and operations.
+  resolve <ref>                 Read one governed record.
+  claims <ref>                  List claims and evidence for a record.
+  context <ref>                 Build a governed record context package.
+  retrieve <query>              Search governed records (v1 registry).
+  ops                           List operations.
+  registrar | conservator       Check claim records | measure Layout patterns in Chromium.
+
+Site compilation: compile, timeline, transcribe, sale, gate, build, shots, probe, workflow (see stylegallery workflow).
+
+  help, --help                  Show this help.
+  version, --version            Show the package version.
+
+Typical agent loop: stylegallery search "sticky header" -> stylegallery read <id> --outline -> stylegallery read <id> --section <slug>.
+MCP server: stylegallery-mcp (tools: search, read, plus governed and compiler tools).
+`;
+
+function report(value) {
+  return { report: value, exitCode: value.ok ? 0 : 1, output: `${JSON.stringify(value, null, 2)}\n` };
+}
+function failure(operation, code, message) { return report({ ok: false, operation, failures: [{ code, message }] }); }
+
+function parseOptions(command, args, specs) {
+  const values = {};
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) { positional.push(argument); continue; }
+    const spec = specs[argument];
+    if (!spec) return { error: failure(command, "argument_unknown", `unknown option ${argument}; run stylegallery help`) };
+    if (Object.hasOwn(values, spec.field)) return { error: failure(command, "argument_duplicate", `${argument} was supplied more than once`) };
+    if (spec.flag) { values[spec.field] = true; continue; }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return { error: failure(command, "argument_value_required", `${argument} requires a value`) };
+    if (spec.integer) {
+      if (!/^[0-9]+$/.test(value)) return { error: failure(command, "argument_integer_invalid", `${argument} must be an unsigned integer`) };
+      values[spec.field] = Number(value);
+    } else values[spec.field] = value;
+    index += 1;
+  }
+  return { values, positional };
+}
+
+async function runSearch(args) {
+  const parsed = parseOptions("search", args, {
+    "--query": { field: "query" }, "--query-en": { field: "query_en" }, "--limit": { field: "limit", integer: true },
+    "--paths-only": { field: "paths_only", flag: true }, "--detailed": { field: "detailed", flag: true },
+  });
+  if (parsed.error) return parsed.error;
+  const { values, positional } = parsed;
+  if (values.query !== undefined && positional.length > 0) return failure("search", "argument_inapplicable", "give the query as words or --query, not both");
+  const query = values.query ?? positional.join(" ");
+  if (!query) return failure("search", "argument_value_required", "a query is required: stylegallery search \"sticky header\"");
+  const { detailed, ...rest } = values;
+  const input = { ...rest, query, ...(detailed ? { response_format: "detailed" } : {}) };
+  const { invokeSearchOperation } = await import("./agent-native/v2/material-search-v3.mjs");
+  const { materialRuntimeOptions } = await import("./agent-native/v2/material-cli-adapter.mjs");
+  return report(invokeSearchOperation("search", input, materialRuntimeOptions()));
+}
+
+async function runRead(args) {
+  const parsed = parseOptions("read", args, { "--section": { field: "section" }, "--outline": { field: "outline", flag: true } });
+  if (parsed.error) return parsed.error;
+  if (parsed.positional.length !== 1) return failure("read", "argument_value_required", "give exactly one id, path, or StableRef: stylegallery read sg:layout/sticky-header");
+  const { invokeSearchOperation } = await import("./agent-native/v2/material-search-v3.mjs");
+  const { materialRuntimeOptions } = await import("./agent-native/v2/material-cli-adapter.mjs");
+  return report(invokeSearchOperation("read", { reference: parsed.positional[0], ...parsed.values }, materialRuntimeOptions()));
+}
+
+async function runRetrieve(args) {
+  const parsed = parseOptions("retrieve", args, { "--query": { field: "query" }, "--limit": { field: "limit", integer: true }, "--format": { field: "format" } });
+  if (parsed.error) return parsed.error;
+  const { format, ...values } = parsed.values;
+  if (format !== undefined && format !== "json") return failure("retrieve", "format_unsupported", "Only --format json is supported.");
+  const query = values.query ?? parsed.positional.join(" ");
+  if (!query) return failure("retrieve", "argument_value_required", "a query is required");
+  const { agentNativeRegistry } = await import("./agent-native/registry.mjs");
+  return report(agentNativeRegistry.invoke("retrieve", { ...values, query }));
+}
+
+export async function runStylegalleryCli(argv, config = {}) {
+  const [command, ...rest] = argv;
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    return { exitCode: 0, output: HELP_TEXT, report: { ok: true, operation: "help" } };
+  }
+  if (command === "version" || command === "--version" || command === "-v") {
+    return { exitCode: 0, output: `${packageVersion()}\n`, report: { ok: true, operation: "version" } };
+  }
+  if (rest.includes("--help")) return { exitCode: 0, output: HELP_TEXT, report: { ok: true, operation: "help" } };
+  if (command === "search") return runSearch(rest);
+  if (command === "read") return runRead(rest);
+  if (command === "retrieve") return runRetrieve(rest);
+  if (command === "context" && rest.includes("--query")) {
+    const { runMaterialCli } = await import("./agent-native/v2/material-cli-adapter.mjs");
+    return runMaterialCli(["context", ...rest]);
+  }
+  const { runSgCli } = await import("./compiler/cli.mjs");
+  return runSgCli(argv, config);
+}

package/skills/stylegallery-search/SKILL.md

@@ -0,0 +1,34 @@
+---
+type: Agent Skill
+name: stylegallery-search
+description: Find and read StyleGallery guidance (layout patterns, recipes, motion, state management, platform guides, design terminology, expression) with the stylegallery CLI or the stylegallery-mcp search/read tools. Use when a UI task needs a layout pattern, recipe, or interaction contract and the right document is not already known.
+---
+
+# StyleGallery search
+
+1. Search with a short task phrase. Pass an English rewrite when you ask in another language:
+
+   ```sh
+   stylegallery search "sticky header"
+   stylegallery search "헤더 고정" --query-en "sticky header"
+   ```
+
+   MCP: `search { "query": "헤더 고정", "query_en": "sticky header" }`.
+
+2. Pick a result by `title`, `description`, and the verbatim `snippets`. Each result has a readable `id` such as `sg:layout/sticky-header` and a `next.read` command.
+
+3. Read only what you need:
+
+   ```sh
+   stylegallery read sg:layout/sticky-header --outline
+   stylegallery read sg:layout/sticky-header --section css
+   ```
+
+   MCP: `read { "reference": "sg:layout/sticky-header", "section": "css" }`.
+
+Notes:
+
+- Results default to 5; use `--limit` (1-50) and `--paths-only` when you will open files yourself.
+- `results: []` is a normal answer. Follow `hint`: add `--query-en`, use fewer words, or browse with `stylegallery discover`.
+- `--detailed` (MCP `response_format: "detailed"`) adds scores and hash identities; you rarely need it.
+- With the repository checked out, you can also read the returned `path` directly.