From c20faf5b0b8d3d37ae2876e3546ad231b63aebde Mon Sep 17 00:00:00 2001 From: bitkyc08-arch Date: Tue, 22 Sep 2026 18:16:08 +0900 Subject: [PATCH 1/3] docs: plan design recipes and credit upstream references --- README.md | 18 ++- .../260922_design_recipe_mcp/000_plan.md | 65 +++++++++++ .../260922_design_recipe_mcp/001_sources.md | 24 ++++ .../260922_design_recipe_mcp/002_decisions.md | 48 ++++++++ .../260922_design_recipe_mcp/003_issues.md | 27 +++++ .../260922_design_recipe_mcp/004_audit.md | 13 +++ .../010_catalog_recipes.md | 63 +++++++++++ .../020_codemode_mcp.md | 54 +++++++++ .../030_recipe_experience.md | 56 +++++++++ docs/ATTRIBUTION.md | 107 ++++++++++++++++++ 10 files changed, 473 insertions(+), 2 deletions(-) create mode 100644 devlog/_plan/260922_design_recipe_mcp/000_plan.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/001_sources.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/002_decisions.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/003_issues.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/004_audit.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/010_catalog_recipes.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/020_codemode_mcp.md create mode 100644 devlog/_plan/260922_design_recipe_mcp/030_recipe_experience.md create mode 100644 docs/ATTRIBUTION.md diff --git a/README.md b/README.md index cd313e2..05cdf0d 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@ claude plugin install design-isms@lidge-jun - Modal detail view with history, prompts, palette, keywords, related ISMs - Development guide per ism: fitting components, build method, verification points - Korean/English UI toggle -- Frontend UI Candidates page with 46 mobile, desktop, and shared patterns -- 46 dedicated live demo animation types for the candidate cards and modals +- Frontend UI Candidates page with 94 entries: 46 interface patterns and 48 visual effects +- 94 dedicated live demo types for the candidate cards and modals - 94 guide images under `assets/images/effects/` - 94 guide WebP previews under `assets/images/thumbs/effects/` - Long-form effect documentation in `assets/data/effects-docs.json` @@ -183,3 +183,17 @@ CSS 레시피에는 필요한 JavaScript 상태 관리와 모션 감소 대응 이미지 교체는 원본·WebP·프롬프트·검토 기록을 함께 갱신합니다. 이전 품질 감사 결과는 해시별 이력으로 보관하며, 후속 결과도 비대상 이미지가 그대로인지 검증합니다. + +## References and acknowledgements + +화면 조합과 에이전트 인터페이스 개선에는 다음 프로젝트의 설계 원칙을 참고합니다. +각 원본의 확인 버전, 적용 범위와 라이선스 고지는 [출처 기록](docs/ATTRIBUTION.md)에 정리했습니다. + +| Project | Reference scope | License | +| --- | --- | --- | +| [StyleGallery](https://github.com/changeroa/StyleGallery) · IYEN | 화면 레시피의 필수·교체 가능 요소, 스크롤 책임, 검증 범위 구분 | Code: MIT / documentation: CC BY 4.0 | +| [Taste Skill](https://github.com/Leonxlnx/taste-skill) · Leonxlnx | 목적에 맞는 디자인 선택, 정보 밀도와 모션의 분리, 기존 디자인 시스템 보존 | MIT | +| [aside-codemode](https://github.com/lidge-jun/aside-codemode) · lidge-jun | 작은 MCP 도구 설명과 필요할 때 조회하는 상세 API | MIT | + +기존 카탈로그 데이터와 이미지의 원본은 이 저장소에 있습니다. 위 프로젝트의 전체 자료나 +프레임워크를 포함한다는 뜻은 아니며, 새 기능의 구현 상태는 해당 PR과 사용 문서를 따릅니다. diff --git a/devlog/_plan/260922_design_recipe_mcp/000_plan.md b/devlog/_plan/260922_design_recipe_mcp/000_plan.md new file mode 100644 index 0000000..63fefc7 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/000_plan.md @@ -0,0 +1,65 @@ +# Design recipes and compact MCP delivery + +The catalog already holds useful visual references and implementation material, but selecting a coherent screen requires hopping between six catalogs. This series adds authored screen recipes and a shared read-only query core, exposes it through one compact MCP tool, and brings the same recipes into the existing index page. + +## Goal and loop specification + +- Archetype: satisfy-spec, docs-only roadmap followed by three dependency-ordered implementation cycles. +- Trigger: owner's 2026-09-22 request to research StyleGallery, Taste Skill and its creator's browser; credit usable sources; publish issues and implementation PRs; inherited subagents authorized. +- Goal: coherent page briefs and a working compact local MCP, delivered in reviewable ordinary PRs. +- Non-goals: merge/deploy/release, framework migration, new hosted service, native GitHub stacks, image generation/replacement, copied third-party browser code, universal accessibility certification. +- Verifier: docs semantic/source review and diff checks in wp0; build, catalog tests, full verify and stage in wp1; real stdio integration/timeout/byte-boundary tests in wp2; real desktop/mobile browser actions, screenshots and full verify in wp3. +- Stop: every accepted issue has a published PR and its own observed checks; all phase criteria met. PR publication is not merging or site deployment. +- Durable record: this numbered unit and native session-bound goalplan. Evidence stays in this unit or ignored qa-artifacts; no private machine information in PR bodies. +- Outcomes: DONE with evidence; NEEDS_HUMAN for missing authority; unresolved checks remain open, never reported passed. Host blocked semantics control blocked status. +- Escalation: unexpected existing user work, unclear upstream identity, or a requirement for privileged installs/paid actions. Read-only investigation continues independently. +- Resources: this repository/worktree and temporary source checkouts; repository GitHub issue/PR access; inherited agents, at most three active independent packets at a time. No user token/time budget was specified. Existing lockfile dependency restoration is necessary project setup, not installation of a new tool or dependency; no package versions change. + +## Current signals and source map + +- Native checkout has unpublished finder repair 98f7565; it is preserved. Work uses an isolated worktree based on origin/main 28d6611. +- 49 ISMs / 94 effects / 18 FAQ entries; six catalogs total 233 entries. Approved image bytes and ledgers stay unchanged. +- src/finder.ts mixes ranking with DOM ownership; src/app-export.ts owns palette inference. Their semantics are not changed in this series. +- assets/data/*.json remains canonical. src/*.ts emits classic scripts into assets/js/*.js. scripts/verify-generated.mjs checks exact source/build parity. +- CatalogShell remains the existing catalog modal owner. AppRuntime and AppDialogA11y remain runtime/accessibility owners. +- scripts/stage-pages.mjs allowlists seven HTML pages and assets only. Node MCP/CLI stays outside assets. +- Baseline npm run verify passed, including 106 quality-contract tests, image hashes and navigation. The first attempt lacked tsc; npm ci --ignore-scripts restored existing lockfile dependencies and the retry passed. +- cxc map is unavailable in the installed plugin, so the structure doc and bounded source reads supplied the module map. + +## Delivery map + +| Phase | Branch / ordinary PR base | Contract | Detailed plan | +| --- | --- | --- | --- | +| wp0 | codex/design-foundations / main | researched attribution, issue map, audited roadmap only | 001_sources.md and 003_issues.md | +| wp1 | codex/design-recipe-core / codex/design-foundations | shared query core and three valid recipes | 010_catalog_recipes.md | +| wp2 | codex/design-codemode-mcp / codex/design-recipe-core | one executable tool, bounded read operations | 020_codemode_mcp.md | +| wp3 | codex/design-recipe-experience / codex/design-codemode-mcp | visible recipe workflow, finder repair, browser QA | 030_recipe_experience.md | + +These are sequential ordinary PRs with manual base dependencies, not parallel branch lanes or native stacks. Main alone changes branches and publishes. Each PR has its own exact-head CI evidence. No merge or branch deletion is authorized. + +## Delegation and design consultation + +V1 spawn_agent with fork_context:true is exposed. Native agent_type is not exposed; the user explicitly requested inherited subagents. The inherited design consultant supplies proposal/reflection evidence under that requested transport; native architect-role routing is unavailable and is not claimed verified. Reviewer uses a separate inherited context. This is a documented transport limitation, not a claim that prompt labels enforce roles. + +- Design consultant: Dalton, handle recorded only in private session evidence; proposal D1-D8 summarized in 002_decisions.md. +- Taste and browser researchers: read-only scoped source packets; findings checked in primary files. +- Foundation implementation scopes: pure core vs authored recipes/tests; MCP scopes: transport/budget vs VM worker; UI scopes: controller vs CSS/HTML, with main integration. +- Same consultant reflects on this concrete roadmap before independent A audit. + +## Verification boundary + +New code test commands do not exist at planning time and are marked planned until their phase implements and runs them. Existing npm run verify ran on the actual source target and passed; it does not yet observe new MCP/recipe files. Each implementation phase adds its relevant test command to verify. Browser screenshot production alone is insufficient: main opens and observes each delivery image. + +## Out of scope + +No new catalog counts, no image changes, no eighth page, no public backlog/reference page, no upstream branding or demo data copying, no global tool/skill installation. The creator's confirmed browser candidate is TasteCode (Apache-2.0), not an MIT browser; only research observations are retained. + +## wp0 documentation delta + +NEW this numbered roadmap/research/decision/issue unit. MODIFY README.md: append a concise source-credit table and link docs/ATTRIBUTION.md; correct legacy 46-candidate/46-demo bullets to 94 total with 46 interface patterns. NEW docs/ATTRIBUTION.md: pinned source URLs/revisions, exact adoption scopes, StyleGallery CC BY documentation credit and change notice, full applicable MIT notices for Taste Skill/aside-codemode/StyleGallery code. TasteCode remains research-only here, not advertised as an MIT dependency. No source/generated/runtime change in this phase. + +Reflection revision 2 folds all six consultant findings: recipe discovery, shared view projection, ten-source snapshot identity, truthful trimmed-page cursors, in-realm-only guest bindings, and the app-language extraction. D8-specific reflection was ALIGNED; the whole-roadmap reflection requested these changes and received overall ALIGNED after revision 2. The three remaining prose clarifications (six catalog arrays vs ten total inputs, browser fetch scope, helper wording) were folded before A. + +## Owner steering: catalog additions allowed + +The owner subsequently authorized adding catalog entries freely when useful. The 49/94/18 figures are the verified baseline, not a permanent scope prohibition under this new instruction. Any new catalog entries require a documented P-phase amendment, source/guide provenance, generated assets where required, count-marker owner updates and the corresponding verifier changes. No entries are added merely to increase the number of cards. Existing immutable baseline evidence is still preserved. This authorization does not require unnecessary additions or weaken any validation criterion. diff --git a/devlog/_plan/260922_design_recipe_mcp/001_sources.md b/devlog/_plan/260922_design_recipe_mcp/001_sources.md new file mode 100644 index 0000000..936a9fd --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/001_sources.md @@ -0,0 +1,24 @@ +# Source research and adoption boundaries + +| Source | Revision | License | Used for | +| --- | --- | --- | --- | +| [StyleGallery](https://github.com/changeroa/StyleGallery) | a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d | Code MIT; docs CC BY 4.0 | Essential/helper/substitutable recipe roles, explicit constraints and evidence scope | +| [Taste Skill](https://github.com/Leonxlnx/taste-skill) | 5217fb45be2c0b302f29c9cd31cbd3237501c684 | MIT, Copyright (c) 2026 Leonxlnx | Purpose-first choice, separate density/motion, preserve existing design system | +| [aside-codemode](https://github.com/lidge-jun/aside-codemode) | b76c911318ebe64f03dffb7bb27b37b23ebab777 | MIT, Copyright (c) 2026 lidge-jun | One execute_code tool and on-demand API discovery | +| [TasteCode](https://github.com/Leonxlnx/tastecode) | 3ee7948d8ec9d3f2ac538c7ac9b6c9fa8e345c28 | Apache-2.0 | Research-only browser-preview settling and DOM-audit observations; no code copied | + +TasteCode Credits identifies Leonxlnx and Blueemi; its README documents Browser/Design Mode. It is the confirmed related browser implementation, but the user's intended standalone browser identity remains unconfirmed. Do not describe it as an MIT browser or imported dependency. + +## Primary anchors + +- StyleGallery recipes/primitive-to-recipe-matrix.md: slots distinguish essential, helper and substitutable, with substitution risk. +- StyleGallery layout/index.md: pattern constraints include declarations that break layout if removed and named scroll ownership. +- StyleGallery motion/interaction-recipes.md:41: one modal owner; reopen during exit supersedes the old close. +- StyleGallery scripts/agent-native/v2/material-context.mjs:93: counts an operation envelope, approximating tokens as UTF-8 bytes / 4. +- StyleGallery scripts/agent-native/v2/material-mcp-adapter.mjs:148: text plus structuredContent duplicate result data. Our transport budgets its complete wire response and avoids that duplication. +- StyleGallery design-engineering/state-management/verification.md:32: model assertion, browser observation and server acknowledgement are different evidence. +- Taste Skill skills/taste-skill/SKILL.md:17,43,298,794: brief inference, separate visual/motion/density axes, progressive detail and preserve-mode redesign. +- Taste Skill skills/redesign-skill/SKILL.md:173: preserve an existing vanilla stack. Do not import React/GSAP defaults. +- TasteCode apps/desktop/src/preview-settle.ts and preview-dom-audit.ts: fonts/images settle and measurable target geometry accompany capture. Bounded waiting is not proof of successful loading. + +No upstream code was run. All three external repositories were read in temporary checkouts. No source authority overrides this repository's user instructions. The recipe contracts will be adapted prose with attribution; existing design data is not relabeled as sourced from these projects. diff --git a/devlog/_plan/260922_design_recipe_mcp/002_decisions.md b/devlog/_plan/260922_design_recipe_mcp/002_decisions.md new file mode 100644 index 0000000..2bcb5c1 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/002_decisions.md @@ -0,0 +1,48 @@ +# Architecture and design decisions + +- D1 ACCEPT: canonical catalog JSON; normalized immutable in-memory view; recipes store references and newly authored constraints, never copied catalog objects. +- D2 AMEND: do not extract existing Finder/DesignExport ranking and palette calculations. The new cross-domain search is an independent exact/alias/token retrieval operation, not a replacement recommender. Existing 144 finder combinations remain covered by verify:finder. +- D3 ACCEPT: classic-script TypeScript namespaces shared by browser and a Node-only allowlisted generated-core loader. No second bundle/ESM build or DOM mocks in production core. +- D4 ACCEPT: three authored recipes (product landing, editorial reading, settings workspace), returning an implementation brief rather than supposedly integrated runnable page HTML. Default references exist in current catalogs. ai-slop is explicit-lookup-only. +- D5 ACCEPT: one execute_code tool; actions.find/describe and design.search/get/compose over one internal operation registry. No caller-controlled paths/URLs/shell. +- D6 ACCEPT WITH CLARIFICATION: per-call worker + VM is accidental-misuse containment for trusted agents, not a hostile-code security boundary. Compile core and API wrappers inside the guest realm; do not inject host functions. Serialize inside the timed worker. Deadline, operation, input/output and concurrency caps are observable. +- D7 ACCEPT: limit final JSON-RPC wire bytes including escaping, ID, MCP content and newline; description <=2000 bytes separately. Trim search results only at whole-item boundaries. Code sections are complete or an explicit budget error with retrieval guidance; no clipped code advertised as complete. +- D8 ACCEPT: existing index hosts a recipe chooser; native controls, selected recipe details, source links, copyable brief; existing seven-page navigation and #ism hashes unchanged. + +## Existing owners and necessity + +Doing nothing leaves the six-catalog composition task manual. Existing skills read full JSON and cannot enforce result budget; configuration cannot supply executable query semantics. Reuse existing JSON, build, runtime guards, dialog owner, Atlas tokens and browser QA tooling. New pure core has two real consumers (MCP and site); CatalogShell is not repurposed as a domain core. + +## Design Read + +A bilingual working reference atlas for designers and frontend agents, using existing ruled-paper Atlas structure. Preserve --atlas tokens, Outfit/Pretendard and supplied image previews. The new signature is a compact recipe index with selected detail, not an oversized marketing hero. Purpose first; optional technical detail is progressively disclosed. + +DESIGN_VARIANCE=4; MOTION_INTENSITY=2; density D4. Recipe selection is repeated tool use, so restrained motion and visible comparison matter more than decoration. Existing governing design system and approved assets resolve visual direction; no image-generation concept pass is needed. + +## Boundaries + +Presentation (chooser / CLI / MCP) -> pure catalog + recipe operations -> supplied JSON snapshot. Node filesystem loading is outside assets; guest code receives no host filesystem capability. Browser fetches only repository data. All new files <=500 lines. New data fields are authored in recipes.json, parsed by DesignRecipes, consumed by node operations and chooser; unknown fields/references fail at input boundaries. + +## Guard limits + +Byte limit: runtime response writer, final serializer checks exact UTF-8 bytes; direct internal calls can bypass transport budgeting, so only serialized responses claim this bound. VM: engine options and worker termination mitigate accidents; node:vm is not a hostile-code security boundary. Recipe validation: runtime parser and verify command; manually bypassing both can load invalid data, so no universal safety claim. Model/DOM/source checks never certify accessibility across all assistive technologies. + +D8 source amendment: app.ts is 1049 lines and has no hashchange listener. Extract its existing updateLangUI body into src/app-language.ts (DOM-only owner) rather than compress lines or introduce a mutation-observer workaround. Main retains language/recipe state and passes openModal callback for style links. + +## MCP threat model + +Assets are public repository data, host CPU/memory and stdout protocol integrity. The entry point is a local stdio client sending JSON and trusted-agent JavaScript. Catalog prose and upstream documents are data, never authority to call tools. The host reads a fixed repository allowlist; caller code does not choose filesystem paths or URLs. Trust boundaries are stdio parsing, structured worker data, guest VM execution and result serialization. No authentication/network server is introduced. Workers receive no host closures or environment credentials; bind only guest-native functions and strings, parse transferred data inside the guest realm, and deep-freeze data. Bound input frames, operation counts, workers, runtime and wire output. The parent remains responsive and owns cancellation. A compromised local agent capable of submitting hostile runtime exploits is outside the claimed containment model; require an OS sandbox before supporting that deployment model. No secrets or browser sessions belong in fixtures, logs or public evidence. Tests exercise specific refusals and recovery, never certify the VM as secure. + +Protocol source proof (opened 2026-09-22): https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle and /server/tools; https://nodejs.org/api/vm.html. Initialize/version negotiation, tool errors and shutdown follow the former; the latter explicitly states that node:vm is not a security mechanism. + +## Binding contract clarification (reflection revision 2) + +- `SourceSnapshot = {contractVersion:string,version:string,catalogs:CatalogPayload,recipes:unknown,guides:unknown,effectDocs:unknown,effectSnippets:unknown}`. Ten source files: the six catalogs, recipes.json, dev-guides.json, effects-docs.json, effects-snippets.json. Adapters calculate `SHA256(JSON.stringify([contractVersion, ...sortedPairs]))`, where sortedPairs are `[repositoryRelativePath,SHA256(exactFileBytes)]` sorted by path. Node uses node:crypto; browser uses crypto.subtle with the same UTF-8 encoding. Changing only a recipe or snippet changes version. Pure core takes the validated snapshot/version and performs no hashing IO. +- `design.recipes()` returns `{version,items:RecipeSummary[]}`; `design.recipes({id})` returns `{version,recipe:Recipe}` including allowed alternatives. It is an internal operation, not another public MCP tool. +- `design.compose({recipeId,selections?:Record,lang?:'ko'|'en'})` returns `{version,composition,brief}`. Unknown slots, duplicate recipe/slot IDs, invalid lang and anti-pattern refs fail. Helper is a supporting role, not an optional/null selection; every declared slot is populated. Missing selections use defaults. +- Shared core view projection: `design.get({domain,id,view?:'summary'|'guide'|'code'|'full'}) -> {version,ref,view,data}`. Default summary uses ISM tagline/description or other domain summary. Guide is dev-guides[id] for ISMs, effects-docs[id] for Effects, relevant implementation fields for other domains; not image-guide prompts. Code returns full effects-snippets.snippets[id] or Layout/Motion snippet. Other code views return VIEW_UNAVAILABLE. Full returns the original catalog entry only. +- Search page is `{version,total,items,nextCursor:string|null,complete}`. Auto-shrink ONLY a directly returned, unmodified original search page; mark it privately in a WeakMap in guest wrappers, never trust a user-shaped object. Nested/projected results receive normal RESPONSE_TOO_LARGE. After sending n items from offset o, cursor advances to o+n, bound to normalized query/filter/version; complete only at the end. Zero fitting items means RESPONSE_TOO_LARGE, not a repeating cursor. Preserve immutable source search page and recompute continuation from trusted metadata. +- Worker input transports coreSources, snapshotJson, registryJson, wrapperSource, code, responseContextJson. No structured-clone object/functions are injected into VM: pass strings, parse/freeze inside guest; wrappers, console and serializer are guest-native. Registry contains serializable metadata/operation IDs. Worker returns only serialized strings; deadline covers getters/toJSON and serialization. Host validates/byte-budgets its final JSON-RPC envelope. VM remains trusted-agent containment, never claimed as a hostile-code sandbox. +- `AppLanguage.render({lang,searchPlaceholder,toggleLabel,footerTitle,footerGenerator}):void` owns DOM work only. RecipeChooser.mount returns setLang/dispose. Main mounts after ISM data readiness, passes openModal callback, updates language and disposes before remount. No MutationObserver or assumed hashchange handler; do not dispose on pagehide without bfcache restoration. + +The core tests and MCP tests must cover recipe discovery, all view availability branches, snapshot changes from each served source class, page shrinking followed by lossless continuation, nested-result rejection, and cross-realm constructor/prototype refusal without injecting host functions. Existing app.ts remains <=1050 lines through the declared language-owner extraction. diff --git a/devlog/_plan/260922_design_recipe_mcp/003_issues.md b/devlog/_plan/260922_design_recipe_mcp/003_issues.md new file mode 100644 index 0000000..5d8d588 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/003_issues.md @@ -0,0 +1,27 @@ +# Issue and PR allocation + +Create only after deduplicating open issues. All eight are accepted delivery scope; link each to its implementation PR. Leave issues open until their changes land; PR creation is not issue completion. + +| Key | Title | Phase | Observable result | +| --- | --- | --- | --- | +| I1 | docs: credit design sources with accurate licenses and pinned provenance | wp0 | README and attribution notes distinguish MIT/CC BY/Apache research; stale 46-demo wording corrected | +| I2 | feat: add a shared deterministic catalog query core | wp1 | six domains, bilingual aliases, stable refs, source version, rejected invalid input | +| I3 | feat: define composable screen recipes with explicit constraints | wp1 | three valid recipes; essential/substitutable slots; unknown and anti-pattern refs refused | +| I4 | feat: expose the design catalog through one Code Mode MCP tool | wp2 | real stdio client can discover, search, get and compose; <=2000B description | +| I5 | fix: enforce complete byte-bounded MCP responses and execution limits | wp2 | Unicode/wrapper budgets, complete snippets, timeout/cancel recovery, no false complete result | +| I6 | feat: add recipe-led discovery to the visual atlas | wp3 | purpose selection, real previews and refs, copyable implementation brief in KO/EN | +| I7 | fix: restore Finder control styling and accessible selection recovery | wp3 | existing finder repair integrated with original authorship; keyboard/focus, errors/retry, language switching checked | +| I8 | test: capture settled desktop/mobile recipe workflows and DOM evidence | wp3 | reproducible browser QA, screenshots plus overflow/targets/images/console observations | + +No issue asks for new fonts, framework migration, unverified browser incorporation or wholesale source copying. URLs are filled from successful GitHub create responses, not predicted numbers. + +## Published issues + +- I1: [docs: credit design sources with accurate licenses and pinned provenance](https://github.com/lidge-jun/design-isms/issues/2) +- I2: [feat: add a shared deterministic catalog query core](https://github.com/lidge-jun/design-isms/issues/3) +- I3: [feat: define composable screen recipes with explicit constraints](https://github.com/lidge-jun/design-isms/issues/4) +- I4: [feat: expose the design catalog through one Code Mode MCP tool](https://github.com/lidge-jun/design-isms/issues/5) +- I5: [fix: enforce complete byte-bounded MCP responses and execution limits](https://github.com/lidge-jun/design-isms/issues/6) +- I6: [feat: add recipe-led discovery to the visual atlas](https://github.com/lidge-jun/design-isms/issues/7) +- I7: [fix: restore Finder control styling and accessible selection recovery](https://github.com/lidge-jun/design-isms/issues/8) +- I8: [test: capture settled desktop/mobile recipe workflows and DOM evidence](https://github.com/lidge-jun/design-isms/issues/9) diff --git a/devlog/_plan/260922_design_recipe_mcp/004_audit.md b/devlog/_plan/260922_design_recipe_mcp/004_audit.md new file mode 100644 index 0000000..5314f79 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/004_audit.md @@ -0,0 +1,13 @@ +# Roadmap review record + +## Design consultation + +Inherited design consultant proposed D1-D8. Main accepted D1/D3-D7, amended D2 to preserve the existing Finder implementation, and amended D8 to extract language DOM updates because app.ts is 1049 lines. Native architect-role selection is unavailable in the exposed tool schema; inherited consultation followed the owner request and this limitation is not represented as verified native routing. + +Reflection 1 found six gaps: recipe discovery, get view semantics, complete snapshot identity, trimmed cursor continuity, guest-realm transfer and language UI ownership. Main added the consistent revision-2 binding contract to the relevant phase plans. Reflection 2 returned ALIGNED with no design blockers; three wording clarifications were applied. Source/implementation tests remain for their implementation phases. + +Independent A review follows separately. + +## Independent A review + +A separate inherited reviewer audited the whole roadmap against current sources. All 18 default and 18 alternative references exist in their declared domains and exclude anti-patterns. The reviewer confirmed source/create and resolve/get contracts. Final verdict: PASS, blocking_issues: []. The remaining nine-versus-ten-source wording was corrected to list effects-docs.json explicitly. No runtime behavior is certified by this plan verdict. diff --git a/devlog/_plan/260922_design_recipe_mcp/010_catalog_recipes.md b/devlog/_plan/260922_design_recipe_mcp/010_catalog_recipes.md new file mode 100644 index 0000000..85bcc23 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/010_catalog_recipes.md @@ -0,0 +1,63 @@ +# Phase 1: shared catalog and recipe contracts + +Depends on wp0 roadmap. Goal: one pure, tested core usable by both browser and Node. No rendered UI/MCP transport in this phase. + +## File delta + +| Action | Path | Change | +| --- | --- | --- | +| NEW | src/design-contracts.ts | DesignCatalog namespace types: Domain = isms/effects/color/typography/layout/motion; Ref = {domain,id}; Summary = {ref,name,nameKr,summary,kind?}; Snapshot with version, catalog arrays and lookup | +| NEW | src/design-catalog.ts | validate and index supplied catalog payload, deterministic search, typed ref resolution and summary projection; no DOM or load-time IO | +| NEW | src/design-recipes.ts | recipe parsing, allowed-selection checking, composition and brief formatting | +| NEW | assets/data/recipes.json | versioned three-recipe source; refs/roles/constraints only, own bilingual labels and attribution | +| NEW | scripts/design-core-loader.mjs | load explicit generated core allowlist with node:vm, read the ten fixed repository JSON paths, compute complete snapshot SHA, expose Node API | +| NEW | scripts/design-core.test.mjs | node:test core acceptance and invalid-input fixtures using real catalog snapshot | +| MODIFY | package.json | add test:design-core and include it in verify; existing build stays tsc -p tsconfig.json | +| GENERATE | assets/js/design-{contracts,catalog,recipes}.js | npm run build, committed classic scripts | +| MODIFY | README.md, structure/README.md, AGENTS.md | document shipped core/recipe SoT and unchanged catalog counts | + +## Complete interface and data contract + +`DesignCatalog.create(source: SourceSnapshot)` returns a validated snapshot. source.catalogs contains six existing arrays; source.version is the adapter-supplied ten-file content hash. source also carries recipes, guides, effectDocs and effectSnippets. Reject duplicate IDs, invalid/missing base fields, unsafe IDs and unknown domains. The core keeps a private index or immutable copies, never mutates inputs. + +`DesignCatalog.search(snapshot,{query,domains?,limit?,cursor?})` returns `{version,total,items,nextCursor,complete}`. Defaults: query empty lists entries, limit 6, max 30. Normalize Unicode and case, resolve exact IDs/names/aliases first, token-match keywords/tagline/summary/alsoCalled/bestFor next. Stable tie order domain/id. Exclude kind=anti-pattern from discovery. Empty and no-match results are truthful. Cursor binds normalized query/filters/offset/version; malformed/stale cursors fail. + +`DesignCatalog.resolve(snapshot,{domain,id})` returns one read-only entry or stable unknown-reference error for internal composition. Public DesignCatalog.get(snapshot,{domain,id,view?}) returns the version/ref/view/data envelope specified below. Explicit get allows ai-slop diagnosis. No file path or arbitrary object member access. + +Recipe shape: `{version:1,recipes:[{id,title:{ko,en},summary:{ko,en},slots:[{id,label:{ko,en},role:'essential'|'helper'|'substitutable',default:{domain,id},alternatives:[Ref]}],constraints:[{ko,en}],checks:[{ko,en}],sources:[{url,license,note}]}]}`. Select defaults from existing IDs, with at least style/layout/color/typography/effect/motion where justified. Not every recipe needs every domain. Content is authored, references immutable existing data. + +`DesignRecipes.parse(raw,snapshot)` validates every default and alternative; rejects ai-slop, unknown fields/roles, duplicate slot IDs and cross-domain alternatives. `compose(snapshot,recipes,{recipeId,selections?,lang?})` validates replacements against the slot's allowlist and returns `{version,recipeId,title,slots:[{id,role,ref,item}],constraints,checks,sources}`. Evidence is design guidance, not runtime-tested implementation. `formatBrief(composition,lang)` returns plain Markdown with refs, constraints, checks and source URLs, no claims of verified product behavior. + +Whole field chain: JSON recipe creation -> JSON transport unchanged -> parse at browser/Node load -> compose + chooser + MCP get/compose -> formatBrief. Source arrays are read by both adapters; no derivative catalog data files. + +## Build order and ownership + +Core worker owns design-contracts.ts/design-catalog.ts. Recipe worker owns design-recipes.ts/recipes.json. Main owns loader, tests, package/docs and build. Same checkout; no worker git operations. New script loader is justified by existing verify-finder VM convention but loads pure core only. Existing Finder and DesignExport remain unchanged. + +## Verification and activation + +Planned command `node --test scripts/design-core.test.mjs` becomes runnable here. Assert real 233 snapshot count, KO/EN/alias search, deterministic tie ordering, cursor continuation and stale rejection, duplicate refs, invalid domain/id, three valid compositions, forbidden alternative and anti-pattern selection, full source fields preserved, brief links, no DOM globals. Compare Node loader output with generated core VM receiving same data. Existing verify:finder protects legacy recommendations. Run build -> verify -> pages:stage and inspect no scripts/mcp/docs leaked into .pages. Expected negative cases are explicit test assertions, not merely error logs. + +Publish ordinary PR against codex/design-foundations, with I2/I3 references and exact-head CI proof. No merge/deploy. + +## Binding contract clarification (reflection revision 2) + +- `SourceSnapshot = {contractVersion:string,version:string,catalogs:CatalogPayload,recipes:unknown,guides:unknown,effectDocs:unknown,effectSnippets:unknown}`. Ten source files: the six catalogs, recipes.json, dev-guides.json, effects-docs.json, effects-snippets.json. Adapters calculate `SHA256(JSON.stringify([contractVersion, ...sortedPairs]))`, where sortedPairs are `[repositoryRelativePath,SHA256(exactFileBytes)]` sorted by path. Node uses node:crypto; browser uses crypto.subtle with the same UTF-8 encoding. Changing only a recipe or snippet changes version. Pure core takes the validated snapshot/version and performs no hashing IO. +- `design.recipes()` returns `{version,items:RecipeSummary[]}`; `design.recipes({id})` returns `{version,recipe:Recipe}` including allowed alternatives. It is an internal operation, not another public MCP tool. +- `design.compose({recipeId,selections?:Record,lang?:'ko'|'en'})` returns `{version,composition,brief}`. Unknown slots, duplicate recipe/slot IDs, invalid lang and anti-pattern refs fail. Helper is a supporting role, not an optional/null selection; every declared slot is populated. Missing selections use defaults. +- Shared core view projection: `design.get({domain,id,view?:'summary'|'guide'|'code'|'full'}) -> {version,ref,view,data}`. Default summary uses ISM tagline/description or other domain summary. Guide is dev-guides[id] for ISMs, effects-docs[id] for Effects, relevant implementation fields for other domains; not image-guide prompts. Code returns full effects-snippets.snippets[id] or Layout/Motion snippet. Other code views return VIEW_UNAVAILABLE. Full returns the original catalog entry only. +- Search page is `{version,total,items,nextCursor:string|null,complete}`. Auto-shrink ONLY a directly returned, unmodified original search page; mark it privately in a WeakMap in guest wrappers, never trust a user-shaped object. Nested/projected results receive normal RESPONSE_TOO_LARGE. After sending n items from offset o, cursor advances to o+n, bound to normalized query/filter/version; complete only at the end. Zero fitting items means RESPONSE_TOO_LARGE, not a repeating cursor. Preserve immutable source search page and recompute continuation from trusted metadata. +- Worker input transports coreSources, snapshotJson, registryJson, wrapperSource, code, responseContextJson. No structured-clone object/functions are injected into VM: pass strings, parse/freeze inside guest; wrappers, console and serializer are guest-native. Registry contains serializable metadata/operation IDs. Worker returns only serialized strings; deadline covers getters/toJSON and serialization. Host validates/byte-budgets its final JSON-RPC envelope. VM remains trusted-agent containment, never claimed as a hostile-code sandbox. +- `AppLanguage.render({lang,searchPlaceholder,toggleLabel,footerTitle,footerGenerator}):void` owns DOM work only. RecipeChooser.mount returns setLang/dispose. Main mounts after ISM data readiness, passes openModal callback, updates language and disposes before remount. No MutationObserver or assumed hashchange handler; do not dispose on pagehide without bfcache restoration. + +The core tests and MCP tests must cover recipe discovery, all view availability branches, snapshot changes from each served source class, page shrinking followed by lossless continuation, nested-result rejection, and cross-realm constructor/prototype refusal without injecting host functions. Existing app.ts remains <=1050 lines through the declared language-owner extraction. + +## Authored default references + +| Recipe | Style | Layout | Color | Typography | Effect | Motion | +| --- | --- | --- | --- | --- | --- | --- | +| product-landing | minimalism | layout-hero-centered | saas-trust-blue | outfit-pretendard-product | sticky-cta-bar | motion-fade | +| editorial-reading | editorial-typography | layout-grid-magazine | media-editorial | noto-serif-sans-kr-readable | scroll-reveal | motion-scroll-reveal | +| settings-workspace | minimalism | layout-form-settings | tailwind-slate-blue | outfit-pretendard-product | toast | motion-expand-collapse | + +Each cell uses the corresponding domain (isms/layout/color/typography/effects/motion). Layout and typography are essential, style/color are substitutable, effects/motion are supporting helpers. Alternatives are explicit, same-domain references selected from current data; no automatic mood-only replacement. Landing alternatives: bauhaus, layout-hero-full-media, minimalism-neutral, noto-serif-sans-kr-readable, copy-confirmation, motion-ease-in-out. Editorial alternatives: minimalism, layout-content-timeline, minimalism-neutral, gowun-batang-pretendard-calm, tooltip, motion-fade. Settings alternatives: bauhaus, layout-form-multi-step, github-primer-light, noto-serif-sans-kr-readable, inline-validation, motion-fade. No alternative is a claim that both complete compositions have been runtime-verified. diff --git a/devlog/_plan/260922_design_recipe_mcp/020_codemode_mcp.md b/devlog/_plan/260922_design_recipe_mcp/020_codemode_mcp.md new file mode 100644 index 0000000..6b24302 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/020_codemode_mcp.md @@ -0,0 +1,54 @@ +# Phase 2: compact read-only Code Mode MCP + +Depends on wp1 shared core. C4 scope is guest execution/input/output; main records honest trusted-agent boundary. Goal: callable local stdio MCP with one small tool. + +## File delta + +| Action | Path | Change | +| --- | --- | --- | +| NEW | scripts/mcp/server.mjs | executable stdio process; framing, initialize/ping/list/call/cancel; per-request controller | +| NEW | scripts/mcp/protocol.mjs | JSON-RPC validation and response shapes, version policy, bounded IDs/input frames | +| NEW | scripts/mcp/operations.mjs | single registry for actions.find/describe and design.search/get/compose signatures/validation/dispatch | +| NEW | scripts/mcp/execution-worker.mjs | isolated per-call guest VM containing trusted generated core, frozen data and in-realm wrappers; serialization stays under deadline | +| NEW | scripts/mcp/execution.mjs | worker lifetime, deadline/cancellation, concurrent-call cap, worker error translation | +| NEW | scripts/mcp/response-budget.mjs | exact UTF-8 serialized wire budget, whole-result fitting, explicit budget errors | +| NEW | scripts/mcp/protocol.test.mjs, scripts/mcp/server.test.mjs | independent stdio-client tests and execution/byte-boundary contracts | +| MODIFY | package.json | mcp script and test:mcp, included in verify; no dependencies | +| MODIFY | docs/PLUGIN.md, README.md, structure/README.md, AGENTS.md | install command/config, example calls, byte budgets and execution trust model | +| MODIFY | skills/style/SKILL.md, skills/effect/SKILL.md | prefer MCP when attached; retain filesystem fallback and original field accuracy | + +Node operational code stays outside public assets. No auto-registration into user clients or global install. Command: `node /absolute/checkout/scripts/mcp/server.mjs`. + +## Public and internal contract + +One tool: `execute_code({code,maxBytes?,timeoutMs?})`. Description <=2000 UTF-8 bytes. maxBytes defaults 8192, range 1024..65536; timeout defaults 3000ms, range 50..10000; code max 32768 UTF-8 bytes. Maximum 4 simultaneous calls and 100 operation invocations per call. Tool result has only one text body (no duplicated structuredContent), plus isError when needed. + +Guest is an async function body with `return`; injected names are `design`, `actions`, and bounded console. `design.search` matches phase1 input/output, `design.get({domain,id,view?})` supports summary/guide/code/full with guide/code loaded from fixed canonical files; `design.compose({recipeId,selections?,lang?})` returns phase1 composition and brief. `actions.find(query)` returns names and short summaries; `actions.describe(name)` returns one signature/schema/example. Unknown operation/args/IDs are clear errors. No process/require/import/fetch/timers/file/network functions are exposed. In-realm wrappers avoid leaking host function constructors. + +Snapshot is read once from fixed paths and content-versioned across six catalog files, recipes.json, dev-guides.json, effects-docs.json and effects-snippets.json (every served content source); source changes require server restart. Worker receives data, core source text and allowlisted registry definition. No client source roots or URLs. Nested code/args validation remains boundary-owned. + +MCP initialization supports explicit known protocol versions (2024-11-05, 2025-03-26, 2025-06-18), chooses supported fallback for unknown requested version, advertises tools only. Require initialization for tool calls; handle ping/initialized/cancelled notifications, unknown tools, parse/invalid request errors. IDs are string <=64 bytes or safe integer. Reject oversized/unterminated input frames; do not let one request kill processing of the next valid frame. stdout is JSON-RPC only; diagnostics on stderr. EOF cancels workers and releases process. + +Response envelope budget includes JSON-RPC wrapper, request ID, nested JSON string escaping and newline. Successful search shrinking removes whole items, adjusts nextCursor/complete, and marks truncated. Any oversized non-search result returns a small error and suggests narrower view/larger allowed budget; never truncate code. Error responses are bounded too. Invalid maxBytes gets a default-bounded error. + +Trust: node:vm/Worker is not a hostile-code security sandbox. This local tool executes trusted-agent JS with accident containment. No claim of executing arbitrary attacker code safely. Deadline terminates synchronous loops, async loops and hostile toJSON; operation cap catches repeated catalog calls; later requests still work. + +## Delegation and verification + +Transport worker: server/protocol/response-budget. Runtime worker: execution/execution-worker/operations. Main owns tests/docs/package and integrates shared contracts before running processes. Workers do not touch the core or branch state. + +Planned `node --test scripts/mcp/*.test.mjs` uses an independent child-process stdio client. Test initialize/list exactly one tool; description byte bound; actual Korean search/get/code/compose; count compatibility; unknown method/tool/args; invalid JSON then recovery; oversized input; Unicode and escaped text at budgets; complete code or explicit size error; stale cursor; cancellation; sync and async infinite loops; throwing getters/toJSON; operation cap; missing Node globals; concurrent calls; EOF teardown. This is executable evidence of tested containment, not security certification. + +Build then full verify/stage; prove operational scripts absent from .pages. Publish ordinary PR against codex/design-recipe-core linked I4/I5, with executed per-head CI. + +## Binding contract clarification (reflection revision 2) + +- `SourceSnapshot = {contractVersion:string,version:string,catalogs:CatalogPayload,recipes:unknown,guides:unknown,effectDocs:unknown,effectSnippets:unknown}`. Ten source files: the six catalogs, recipes.json, dev-guides.json, effects-docs.json, effects-snippets.json. Adapters calculate `SHA256(JSON.stringify([contractVersion, ...sortedPairs]))`, where sortedPairs are `[repositoryRelativePath,SHA256(exactFileBytes)]` sorted by path. Node uses node:crypto; browser uses crypto.subtle with the same UTF-8 encoding. Changing only a recipe or snippet changes version. Pure core takes the validated snapshot/version and performs no hashing IO. +- `design.recipes()` returns `{version,items:RecipeSummary[]}`; `design.recipes({id})` returns `{version,recipe:Recipe}` including allowed alternatives. It is an internal operation, not another public MCP tool. +- `design.compose({recipeId,selections?:Record,lang?:'ko'|'en'})` returns `{version,composition,brief}`. Unknown slots, duplicate recipe/slot IDs, invalid lang and anti-pattern refs fail. Helper is a supporting role, not an optional/null selection; every declared slot is populated. Missing selections use defaults. +- Shared core view projection: `design.get({domain,id,view?:'summary'|'guide'|'code'|'full'}) -> {version,ref,view,data}`. Default summary uses ISM tagline/description or other domain summary. Guide is dev-guides[id] for ISMs, effects-docs[id] for Effects, relevant implementation fields for other domains; not image-guide prompts. Code returns full effects-snippets.snippets[id] or Layout/Motion snippet. Other code views return VIEW_UNAVAILABLE. Full returns the original catalog entry only. +- Search page is `{version,total,items,nextCursor:string|null,complete}`. Auto-shrink ONLY a directly returned, unmodified original search page; mark it privately in a WeakMap in guest wrappers, never trust a user-shaped object. Nested/projected results receive normal RESPONSE_TOO_LARGE. After sending n items from offset o, cursor advances to o+n, bound to normalized query/filter/version; complete only at the end. Zero fitting items means RESPONSE_TOO_LARGE, not a repeating cursor. Preserve immutable source search page and recompute continuation from trusted metadata. +- Worker input transports coreSources, snapshotJson, registryJson, wrapperSource, code, responseContextJson. No structured-clone object/functions are injected into VM: pass strings, parse/freeze inside guest; wrappers, console and serializer are guest-native. Registry contains serializable metadata/operation IDs. Worker returns only serialized strings; deadline covers getters/toJSON and serialization. Host validates/byte-budgets its final JSON-RPC envelope. VM remains trusted-agent containment, never claimed as a hostile-code sandbox. +- `AppLanguage.render({lang,searchPlaceholder,toggleLabel,footerTitle,footerGenerator}):void` owns DOM work only. RecipeChooser.mount returns setLang/dispose. Main mounts after ISM data readiness, passes openModal callback, updates language and disposes before remount. No MutationObserver or assumed hashchange handler; do not dispose on pagehide without bfcache restoration. + +The core tests and MCP tests must cover recipe discovery, all view availability branches, snapshot changes from each served source class, page shrinking followed by lossless continuation, nested-result rejection, and cross-realm constructor/prototype refusal without injecting host functions. Existing app.ts remains <=1050 lines through the declared language-owner extraction. diff --git a/devlog/_plan/260922_design_recipe_mcp/030_recipe_experience.md b/devlog/_plan/260922_design_recipe_mcp/030_recipe_experience.md new file mode 100644 index 0000000..37fd0e8 --- /dev/null +++ b/devlog/_plan/260922_design_recipe_mcp/030_recipe_experience.md @@ -0,0 +1,56 @@ +# Phase 3: recipe-led atlas and interaction verification + +Depends on wp1 core; delivered after wp2 so documented MCP and browser share the final composition contract. C3 visible UI work. + +## File delta + +| Action | Path | Change | +| --- | --- | --- | +| NEW | src/app-language.ts | own existing updateLangUI DOM work; preserve placeholders, lang attribute, toggle label and footer strings | +| NEW | src/recipe-chooser.ts | independently mounted recipe controller and async data state; use shared core/recipes | +| NEW | assets/css/recipe-chooser.css | Atlas layout, chooser/details/preview composition, responsive and reduced-motion states | +| MODIFY | index.html | mount recipe section after catalog-entry and before existing filters; load three core scripts plus app-language and chooser in explicit order, stylesheet after theme/nav | +| MODIFY | src/app.ts | extract existing updateLangUI body into AppLanguage.render with supplied translated labels; mount/dispose/language-sync recipe controller; preserve initial hash and ISM modal callbacks; keep app.ts <=1050 lines | +| MODIFY | assets/css/finder.css, index.html | carry existing authored finder styling repair from 98f7565 without altering native checkout; preserve credit/history when feasible | +| NEW | scripts/qa-recipes.mjs | agbrowse script-mode scenario exporting default(ctx), settles fonts/images, performs user interactions, emits measurements and screenshot paths | +| GENERATE | assets/js/app-language.js, assets/js/recipe-chooser.js, assets/js/app.js | npm run build outputs | +| MODIFY | README.md, structure/README.md, AGENTS.md | shipped recipe experience, QA command and source ownership | +| NEW | devlog unit evidence images and numbered verification report | observed desktop/mobile screenshots, measured checks, exact revision and limitations | + +## UI contract and layout + +Use existing Atlas token surface and typography. Recipe heading describes task: KO '어떤 화면을 만들고 있나요?' / EN 'What are you building?'. Three purpose choices use native radio controls in a fieldset; desktop is a compact left selection list and a wider selected-detail column. Mobile places a short selector before the detail. No eighth page, nav change, marketing hero, duplicated catalog grid or framework. + +Render title, brief rationale, a bounded real existing WebP preview with reserved aspect ratio, selected style/layout/type/color refs, essential vs helper/substitutable roles, constraints and checks. Use existing link routes (index.html#id, effects.html#id, domain.html#id); clicking a style ref MUST prevent fragment-only navigation and delegate openIsm: existing app.ts only reads hash at startup and has no hashchange listener. 'Copy brief' is the primary action; technical constraints and source attribution live under details. Do not show implementation internals unless they help choose/apply a recipe. + +`RecipeChooser.mount({root,getLang,openIsm})` returns `{setLang,dispose}`. Fetch recipes first, then the ten versioned JSON source files when user expands/selects workflow; coalesce one promise. Boundary errors show retry; leave original catalog usable. Avoid full raw snippets in initial render. Selection is local (no conflict with #ism hash); after language change retain selection and opened details. Native controls provide keyboard behavior. Live status announces copy success/failure; clipboard rejection offers selectable textarea/manual copy, not false success. + +Use textContent or escaped strings for all data-derived markup. Validate every link from domain/id mapping, never source-provided javascript URLs. async run token prevents stale completion after dispose/retry; teardown removes listeners and invalidates pending UI effects; call dispose before remount, not on pagehide without a bfcache restoration strategy. AppLanguage.render receives only lang/searchPlaceholder/toggleLabel/footerTitle/footerGenerator, never app state or t(). Preserve existing AppRuntime storage/history and loading behavior. + +## Finder integration + +The isolated origin/main baseline lacks CSS for the already present finder trigger/dialog. Reuse reviewed unpublished repair 98f7565 while retaining original commit authorship where possible; do not rewrite/delete the original commit. Verify trigger geometry, actual dialog open, all three answer stages, ranked result, Escape/backdrop/close and restored focus. New recipe UI does not take over Finder or alter existing recommendation outputs. + +## QA and activation + +Use existing agbrowse, no new browser driver. Command planned: `agbrowse script scripts/qa-recipes.mjs --allow-script --trace-out qa-artifacts/recipes -- http://127.0.0.1:4187`. Script should produce deterministic viewport captures (1440x900, 390x844), await document.fonts.ready and visible images with recorded outcome, assert no horizontal overflow and no browser console errors, and record target geometry/image failures. No arbitrary sleep masquerades as readiness. + +Exercise selection and copy, KO/EN switch, source navigation/hash modal, keyboard tab/radio selection, Finder open/result/close/focus return, reduced-motion, long labels, empty/failed recipes fetch then retry, and clipboard denial fallback. Use request interception only in QA to trigger errors, restoring route afterward. Inspect screenshots with image viewer, fix visible issues and repeat affected states. + +Run build -> full verify -> pages:stage; browser QA also covers Effects desktop/mobile card count 94 and unique demo type 94, no overflow/errors. Publish per-PR current SHA and hosted checks, with screenshot evidence. This does not certify screen readers or real mobile hardware. + +## SoT and completion + +Update all current docs and source/generated parity together. Preserve approved image manifests and 49/94/18 markers. Link I6/I7/I8 to ordinary PR against codex/design-codemode-mcp. Keep the unit in _plan until all phases finish, then move once to _fin and update links; record no merge/deploy performed. + +## Binding contract clarification (reflection revision 2) + +- `SourceSnapshot = {contractVersion:string,version:string,catalogs:CatalogPayload,recipes:unknown,guides:unknown,effectDocs:unknown,effectSnippets:unknown}`. Ten source files: the six catalogs, recipes.json, dev-guides.json, effects-docs.json, effects-snippets.json. Adapters calculate `SHA256(JSON.stringify([contractVersion, ...sortedPairs]))`, where sortedPairs are `[repositoryRelativePath,SHA256(exactFileBytes)]` sorted by path. Node uses node:crypto; browser uses crypto.subtle with the same UTF-8 encoding. Changing only a recipe or snippet changes version. Pure core takes the validated snapshot/version and performs no hashing IO. +- `design.recipes()` returns `{version,items:RecipeSummary[]}`; `design.recipes({id})` returns `{version,recipe:Recipe}` including allowed alternatives. It is an internal operation, not another public MCP tool. +- `design.compose({recipeId,selections?:Record,lang?:'ko'|'en'})` returns `{version,composition,brief}`. Unknown slots, duplicate recipe/slot IDs, invalid lang and anti-pattern refs fail. Helper is a supporting role, not an optional/null selection; every declared slot is populated. Missing selections use defaults. +- Shared core view projection: `design.get({domain,id,view?:'summary'|'guide'|'code'|'full'}) -> {version,ref,view,data}`. Default summary uses ISM tagline/description or other domain summary. Guide is dev-guides[id] for ISMs, effects-docs[id] for Effects, relevant implementation fields for other domains; not image-guide prompts. Code returns full effects-snippets.snippets[id] or Layout/Motion snippet. Other code views return VIEW_UNAVAILABLE. Full returns the original catalog entry only. +- Search page is `{version,total,items,nextCursor:string|null,complete}`. Auto-shrink ONLY a directly returned, unmodified original search page; mark it privately in a WeakMap in guest wrappers, never trust a user-shaped object. Nested/projected results receive normal RESPONSE_TOO_LARGE. After sending n items from offset o, cursor advances to o+n, bound to normalized query/filter/version; complete only at the end. Zero fitting items means RESPONSE_TOO_LARGE, not a repeating cursor. Preserve immutable source search page and recompute continuation from trusted metadata. +- Worker input transports coreSources, snapshotJson, registryJson, wrapperSource, code, responseContextJson. No structured-clone object/functions are injected into VM: pass strings, parse/freeze inside guest; wrappers, console and serializer are guest-native. Registry contains serializable metadata/operation IDs. Worker returns only serialized strings; deadline covers getters/toJSON and serialization. Host validates/byte-budgets its final JSON-RPC envelope. VM remains trusted-agent containment, never claimed as a hostile-code sandbox. +- `AppLanguage.render({lang,searchPlaceholder,toggleLabel,footerTitle,footerGenerator}):void` owns DOM work only. RecipeChooser.mount returns setLang/dispose. Main mounts after ISM data readiness, passes openModal callback, updates language and disposes before remount. No MutationObserver or assumed hashchange handler; do not dispose on pagehide without bfcache restoration. + +The core tests and MCP tests must cover recipe discovery, all view availability branches, snapshot changes from each served source class, page shrinking followed by lossless continuation, nested-result rejection, and cross-realm constructor/prototype refusal without injecting host functions. Existing app.ts remains <=1050 lines through the declared language-owner extraction. diff --git a/docs/ATTRIBUTION.md b/docs/ATTRIBUTION.md new file mode 100644 index 0000000..2d22aef --- /dev/null +++ b/docs/ATTRIBUTION.md @@ -0,0 +1,107 @@ +# Source and adaptation notices + +These references inform the recipe/MCP improvement series. A reference is not a dependency, endorsement, or a claim that all upstream rules are adopted. Existing catalog data and generated images retain their existing provenance. + +| Project | Pinned revision | Scope | +| --- | --- | --- | +| [StyleGallery](https://github.com/changeroa/StyleGallery) by IYEN | [a891175](https://github.com/changeroa/StyleGallery/tree/a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d) | Recipe roles, composition constraints and distinctions between declared guidance and executed evidence | +| [Taste Skill](https://github.com/Leonxlnx/taste-skill) by Leonxlnx | [5217fb4](https://github.com/Leonxlnx/taste-skill/tree/5217fb45be2c0b302f29c9cd31cbd3237501c684) | Purpose-first design, density/motion separation, preserve-mode redesign | +| [aside-codemode](https://github.com/lidge-jun/aside-codemode) by lidge-jun | [b76c911](https://github.com/lidge-jun/aside-codemode/tree/b76c911318ebe64f03dffb7bb27b37b23ebab777) | One-tool Code Mode and progressive API discovery | + +## StyleGallery documentation adaptation + +StyleGallery code uses MIT; its documentation uses [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/). Copyright (c) 2026 IYEN. See the pinned [NOTICE](https://github.com/changeroa/StyleGallery/blob/a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d/NOTICE) and [documentation license](https://github.com/changeroa/StyleGallery/blob/a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d/LICENSE-DOCS). + +Referenced works: [Primitive To Recipe Matrix](https://github.com/changeroa/StyleGallery/blob/a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d/recipes/primitive-to-recipe-matrix.md), [Layout contract](https://github.com/changeroa/StyleGallery/blob/a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d/layout/index.md), and [Webpage Generation Workflow](https://github.com/changeroa/StyleGallery/blob/a89117593cbd1e7c5642f2e512a6a7bcf5e4ec0d/guides/webpage-generation-workflow.md). + +Changes: the planned adaptation selects the essential/helper/substitutable role model and expresses it as bilingual recipes referencing this repository's own catalog IDs. It omits the upstream governance workflow and adapts constraints/checks for this site's existing patterns. Imported or adapted recipe prose must keep its source and license fields. No claim of endorsement or universal verification is made. + +## Research-only browser reference + +[TasteCode](https://github.com/Leonxlnx/tastecode/tree/3ee7948d8ec9d3f2ac538c7ac9b6c9fa8e345c28), by Leonxlnx and Blueemi, includes a Browser/Design Mode. Its license is Apache-2.0, not MIT. We inspected its preview-settling and DOM-audit workflow; no TasteCode code, branding, assets or runtime is included. The identity of any separate standalone browser intended by the original request remains unconfirmed. + +## MIT notices + +The following upstream notices are preserved for source traceability and any adaptations in this series. They apply to their respective upstream material, not to unrelated catalog images or to StyleGallery's CC BY documentation. + +### Taste Skill + +```text +MIT License + +Copyright (c) 2026 Leonxlnx + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +### aside-codemode + +```text +MIT License + +Copyright (c) 2026 lidge-jun + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and +associated documentation files (the "Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the +following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial +portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT +LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO +EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE +USE OR OTHER DEALINGS IN THE SOFTWARE. +``` + +### StyleGallery source code + +```text +MIT License + +Copyright (c) 2026 IYEN + +This license applies to the source code in this repository: scripts, CLI and +MCP server implementations, the website and server code under `site/`, +validators, and test code. The Markdown documentation, pattern and recipe +prose, and domain documents are licensed separately under CC BY 4.0; see +LICENSE-DOCS. Third-party material adapted into this repository keeps its +original rights; see NOTICE. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` From 26afefc557fc37b9681af085eedfe19a657b53e2 Mon Sep 17 00:00:00 2001 From: bitkyc08-arch Date: Tue, 22 Sep 2026 18:18:44 +0900 Subject: [PATCH 2/3] docs: record roadmap verification and clarify attribution --- devlog/_plan/260922_design_recipe_mcp/000_plan.md | 6 ++++++ devlog/_plan/260922_design_recipe_mcp/004_audit.md | 4 ++++ docs/ATTRIBUTION.md | 2 +- 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/devlog/_plan/260922_design_recipe_mcp/000_plan.md b/devlog/_plan/260922_design_recipe_mcp/000_plan.md index 63fefc7..6f79659 100644 --- a/devlog/_plan/260922_design_recipe_mcp/000_plan.md +++ b/devlog/_plan/260922_design_recipe_mcp/000_plan.md @@ -63,3 +63,9 @@ Reflection revision 2 folds all six consultant findings: recipe discovery, share ## Owner steering: catalog additions allowed The owner subsequently authorized adding catalog entries freely when useful. The 49/94/18 figures are the verified baseline, not a permanent scope prohibition under this new instruction. Any new catalog entries require a documented P-phase amendment, source/guide provenance, generated assets where required, count-marker owner updates and the corresponding verifier changes. No entries are added merely to increase the number of cards. Existing immutable baseline evidence is still preserved. This authorization does not require unnecessary additions or weaken any validation criterion. + +## wp0 conclusion and next direction + +The docs-only roadmap is implemented and independently reviewed. Issues #2–#9 and [PR #10](https://github.com/lidge-jun/design-isms/pull/10) are published. Source/license comparison, staged diff checks and sot:check (13 markers, 49/94/18) passed. Hosted PR run 35709477981 at c20faf5 executed verify and pages:stage successfully; later documentation-only follow-up heads need their own current-head check before PR readiness. No application/image changes or deployment occurred. + +Next direction: wp1 consumes 010_catalog_recipes.md to implement the shared core and three authored recipes. Existing Finder math stays unchanged. The upstream browser identity is not generalized beyond the confirmed TasteCode research candidate. No hypothesis about automatic page composition or hostile-code isolation is represented as proven. diff --git a/devlog/_plan/260922_design_recipe_mcp/004_audit.md b/devlog/_plan/260922_design_recipe_mcp/004_audit.md index 5314f79..e06ffa8 100644 --- a/devlog/_plan/260922_design_recipe_mcp/004_audit.md +++ b/devlog/_plan/260922_design_recipe_mcp/004_audit.md @@ -11,3 +11,7 @@ Independent A review follows separately. ## Independent A review A separate inherited reviewer audited the whole roadmap against current sources. All 18 default and 18 alternative references exist in their declared domains and exclude anti-patterns. The reviewer confirmed source/create and resolve/get contracts. Final verdict: PASS, blocking_issues: []. The remaining nine-versus-ten-source wording was corrected to list effects-docs.json explicitly. No runtime behavior is certified by this plan verdict. + +## C reader and source review + +Independent final-doc review returned PASS at c20faf5. The three MIT notices matched upstream license text exactly (ignoring surrounding whitespace); the CC BY author/source/license/change notice was confirmed; README counts matched data. Public-reader confusion about an unidentified original request was removed from ATTRIBUTION and remains only in the research record. No runtime feature is claimed shipped. diff --git a/docs/ATTRIBUTION.md b/docs/ATTRIBUTION.md index 2d22aef..6f4095e 100644 --- a/docs/ATTRIBUTION.md +++ b/docs/ATTRIBUTION.md @@ -18,7 +18,7 @@ Changes: the planned adaptation selects the essential/helper/substitutable role ## Research-only browser reference -[TasteCode](https://github.com/Leonxlnx/tastecode/tree/3ee7948d8ec9d3f2ac538c7ac9b6c9fa8e345c28), by Leonxlnx and Blueemi, includes a Browser/Design Mode. Its license is Apache-2.0, not MIT. We inspected its preview-settling and DOM-audit workflow; no TasteCode code, branding, assets or runtime is included. The identity of any separate standalone browser intended by the original request remains unconfirmed. +[TasteCode](https://github.com/Leonxlnx/tastecode/tree/3ee7948d8ec9d3f2ac538c7ac9b6c9fa8e345c28), by Leonxlnx and Blueemi, includes a Browser/Design Mode. Its license is Apache-2.0, not MIT. We inspected its preview-settling and DOM-audit workflow; no TasteCode code, branding, assets or runtime is included. ## MIT notices From f5763774a7d650f0bfc0c439f2efb988e53ef29f Mon Sep 17 00:00:00 2001 From: bitkyc08-arch Date: Tue, 22 Sep 2026 18:23:57 +0900 Subject: [PATCH 3/3] docs: target the design improvement series at dev --- devlog/_plan/260922_design_recipe_mcp/000_plan.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/devlog/_plan/260922_design_recipe_mcp/000_plan.md b/devlog/_plan/260922_design_recipe_mcp/000_plan.md index 6f79659..3ea4c11 100644 --- a/devlog/_plan/260922_design_recipe_mcp/000_plan.md +++ b/devlog/_plan/260922_design_recipe_mcp/000_plan.md @@ -30,7 +30,7 @@ The catalog already holds useful visual references and implementation material, | Phase | Branch / ordinary PR base | Contract | Detailed plan | | --- | --- | --- | --- | -| wp0 | codex/design-foundations / main | researched attribution, issue map, audited roadmap only | 001_sources.md and 003_issues.md | +| wp0 | codex/design-foundations / dev | researched attribution, issue map, audited roadmap only | 001_sources.md and 003_issues.md | | wp1 | codex/design-recipe-core / codex/design-foundations | shared query core and three valid recipes | 010_catalog_recipes.md | | wp2 | codex/design-codemode-mcp / codex/design-recipe-core | one executable tool, bounded read operations | 020_codemode_mcp.md | | wp3 | codex/design-recipe-experience / codex/design-codemode-mcp | visible recipe workflow, finder repair, browser QA | 030_recipe_experience.md | @@ -69,3 +69,7 @@ The owner subsequently authorized adding catalog entries freely when useful. The The docs-only roadmap is implemented and independently reviewed. Issues #2–#9 and [PR #10](https://github.com/lidge-jun/design-isms/pull/10) are published. Source/license comparison, staged diff checks and sot:check (13 markers, 49/94/18) passed. Hosted PR run 35709477981 at c20faf5 executed verify and pages:stage successfully; later documentation-only follow-up heads need their own current-head check before PR readiness. No application/image changes or deployment occurred. Next direction: wp1 consumes 010_catalog_recipes.md to implement the shared core and three authored recipes. Existing Finder math stays unchanged. The upstream browser identity is not generalized beyond the confirmed TasteCode research candidate. No hypothesis about automatic page composition or hostile-code isolation is represented as proven. + +## Owner steering: dev integration target + +The owner directed development to dev after PR #10 was opened. No remote dev branch existed, so dev was created at the unchanged origin/main baseline 28d6611. PR #10 now targets dev; subsequent ordinary PRs keep their manual dependency bases, with dev as the integration root. No main update or deployment is part of this change.