@01.works/reference-client

@01.works/reference-client

정적 portable manifest와 Scaffold Builders API의 manifest를 같은 방식으로 읽는 프레임워크 비종속 ESM client입니다.

pnpm add @01.works/reference-client

import { loadLayoutMap, loadLayoutPackage } from "@01.works/reference-client";

const layout = await loadLayoutPackage(manifestUrl);
const desktopMap = await loadLayoutMap(layout, "desktop");

loadLayoutMap은 byte length와 SHA-256, runtime schema뿐 아니라 manifest의 viewport/document 크기와 final URL 일치 여부도 검증합니다.

Revision-pinned reference 응답도 같은 bounded transport와 runtime contract로 검증합니다.

import { loadLayoutReference } from "@01.works/reference-client";

const { referenceBundle } = await loadLayoutReference("RUN_ID", {
  endpoint: "https://scaffold.builders",
});

Layout overlay workflows

검증된 reference bundle로 구현 프롬프트와 현재 viewport의 오버레이 기반 수정 프롬프트를 만들 수 있습니다. 워크플로 API는 package root와 @01.works/reference-client/workflows에서 모두 제공합니다.

import {
  isLayoutPromptReady,
  loadLayoutReference,
  renderLayoutSetupPrompt,
} from "@01.works/reference-client";

const { referenceBundle } = await loadLayoutReference("RUN_ID");

// 기본 워크플로. 대상 저장소가 기존 프로젝트인지 greenfield인지는 프롬프트를 받은
// 에이전트가 실제 코드를 보고 판정하므로 호출부가 미리 분류하지 않습니다.
const prompt = renderLayoutSetupPrompt(referenceBundle, {
  foundationInstruction: "현재 프로젝트의 foundation과 컴포넌트를 보존해줘.",
});

setup은 agent-ready reference이면 항상 사용할 수 있습니다. initial viewport alignment evidence가 있으면 프롬프트가 observed guide와 1 CSS px 검증을 지시하고, 없으면 관찰 자료만 사용하도록 지시하며 결과에 정렬 근거 미검증을 남기게 합니다. 차단하지 않고 프롬프트 내용만 달라집니다.

생성 절차는 범위 확정 → 주요 구조 구현 → 최소 검증 세 단계입니다. foundation 연결과 오류는 UI 작성 전에 확인하고, route·주요 콘텐츠·기능·제외 범위를 먼저 고정합니다. global guide + 필요한 page 확장, 실제 selector/edge 대응, 최종 clean 화면 비교와 branch별 실제 동작 확인은 유지합니다. direct/derived 분류표나 장문의 gate별 PASS 보고서는 요구하지 않습니다. 작은 기존 화면 수정은 skeleton을 다시 만들지 않습니다. 프롬프트 테스트는 계약 전달만 검증합니다. 새 구현의 품질은 아래 독립 검수로 판단합니다. 보이는 control의 실제 목적지·독립 상태·모바일 workflow와 skip/overlay/가로 overflow는 첫 제출 전에 실제 조작하되, 개별 사이트의 결함 목록을 프롬프트에 복제하지 않습니다.

Dogfood 검수자 체크리스트

복사 프롬프트를 받은 구현자와 별도의 세션에서 검수합니다. 아래는 검수용이며 복사 입력에 별도 장문 지시로 덧붙이지 않습니다. 첫 제출을 고쳐서 최초 통과 결과로 바꾸지 않습니다. 첫 제출이 실패하면 그 소스·증거·판정을 보존한 뒤, 같은 구현자가 검수 피드백을 재현하고 수정하는 라운드를 별도로 수행할 수 있습니다. 독립 재검수 후에도 첫 제출 품질과 수정 후 완성도를 구분하며, 수정 횟수를 미리 제한합니다. 부모가 대신 코드를 고치는 방식은 사용하지 않습니다.

• 입력 revision, 사전 범위 표, 최종 source hash를 확인합니다. 구현자가 제외 항목이나 반복 목록의 범위를 줄였다면 동일 조건 개선으로 집계하지 않습니다.
• 같은 capture viewport의 reference/target clean 화면을 비교합니다. 주요 영역·공백·밀도· 읽기 순서와 목록 처음/중간/끝을 보고, global GNB/action/body 및 page edge를 실제 측정합니다. 같은 token을 쓰는 것과 reference에 맞는 것은 별개입니다. 수치 근거 없는 화면은 정밀 정렬 미검증입니다.
• 서로 다른 desktop/mobile control을 각각 조작합니다. 목적지 내용, 필터/Next의 실제 미리보기, A→B→A 항목 상태, keyboard focus, dialog가 있는 경우 focus 순환·Escape·복귀를 확인합니다.
• 실제 breakpoint 양쪽과 내부 레이블 가독성·clipping을 확인합니다. 긴 카피 stress는 위험 영역만 합니다. WCAG와 best-practice 규칙을 구분하고 serious incomplete는 수동 근거 없이 PASS로 바꾸지 않습니다.
• 캡처·접근성 원본 출력·재현 증거를 제출 hash에 연결합니다. 요약만 있거나 과거 캡처면 실행 여부를 추측하지 말고 미검증 범위를 적습니다. 버그와 증거 누락은 구분해서 보고합니다.

반복 실험에서는 같은 reference·foundation·기능 범위와 모델 설정을 유지하고, 한 번에 한 절차 가설만 바꿉니다. 새 구현 한 번의 결함 수로 개선 효과를 단정하지 않습니다. 레이아웃 전달 결과와 전체 앱 완성도는 별도로 보고하되, 기능 실패를 레이아웃 통과로 면제하지 않습니다. foundation 사전 확인 실패 시 새 앱을 반복 생성하지 말고 연결 문제부터 별도 해결합니다.

revise는 요청한 viewport에 실제 layoutMap 또는 overlay artifact가 있을 때만 준비된 것으로 판정합니다. 사용자가 특정 viewport의 오버레이를 보고 있을 때만 사용하세요.

const activeViewport = "desktop";
if (isLayoutPromptReady(referenceBundle.layout, "revise", activeViewport)) {
  const revision = renderLayoutSetupPrompt(referenceBundle, {
    activeViewport,
    workflow: "revise",
  });
}

여러 reference에는 renderCombinedLayoutSetupPrompt()를 사용하세요. alignment evidence가 있는 reference와 없는 reference가 섞이면 전자를 정렬 anchor로, 후자를 composition 참고로 구분해 프롬프트에 명시합니다. title로 생성 프롬프트 제목을 바꿀 수 있으며, revise에서는 readiness 검사와 renderer에 같은 activeViewport를 전달해야 합니다.

0.4.2 의미 변경

setup 프롬프트의 다섯 gate를 세 단계로 축소하면서, label과 실제 콘텐츠 결과, 상태 격리·복원, 모바일 핵심 workflow, skip/dialog focus, overlay 동작과 내부 clipping을 최소 실행 검증으로 명시합니다. 독립 cold review 완료 조건은 유지합니다.

0.4.1 의미 변경

setup 프롬프트는 global layout contract와 sparse page extension을 분리하고, consumer closure, clean composition 비교, visible-control 확인 및 구현 비참여자의 fresh-session cold review를 완료 조건으로 요구합니다.

0.4.0 의미 변경

setup은 더 이상 "빈 프로젝트 초기 셋업"이 아니라 대상 저장소 상태를 프롬프트 안에서 판정하는 adaptive 워크플로입니다. 기존 align이 하던 "기존 화면 보존 후 정리"를 흡수했으므로 align은 setup의 deprecated alias이며 다음 major에서 제거합니다. setup의 alignment evidence readiness 게이트도 제거됐습니다. resolveLayoutPromptMode()는 선택할 모드가 없어져 deprecated입니다.

이 client는 프롬프트와 readiness를 제공하며 DOM을 변경하지 않습니다. 개발 화면에 실제 live guide를 표시하려면 @01.works/layout-overlay를 개발 의존성으로 설치하고, React의 LayoutOverlay props 또는 framework-neutral mountLayoutOverlay().update()에 채택한 guide를 연결하세요.

폴더를 저장하고 읽는 catalogue API도 같은 package에서 사용할 수 있습니다. 개인 token은 서버에 저장하지 않고 client 인스턴스의 요청 header에만 사용합니다.

import { createCatalogueClient } from "@01.works/reference-client";

const catalogue = createCatalogueClient({
  endpoint: "https://scaffold.builders",
  token: process.env.DESIGN_CONTEXT_TOKEN,
});
const folders = await catalogue.listFolders();
const saved = await catalogue.addFolderUrl(folders[0].id, "https://example.com/work");
const page = await catalogue.listFolderItems(folders[0].id, { limit: 100 });

폴더 client는 생성·수정·삭제, URL 또는 layout 저장, 메모, 순서 변경과 cursor pagination을 지원합니다. 실패 시 CatalogueApiError의 status, code, details로 HTTP 오류를 구분할 수 있습니다.

HTTP transport만 담당하며 UI, 인증 상태, Worker binding에는 의존하지 않습니다. manifest와 artifact는 같은 origin의 portable package 경계 안에서 해석되며, manifest와 layout map은 크기를 제한하며, layout map은 MIME type, SHA-256, canonical contract를 모두 검증한 뒤 반환합니다. 두 loader 모두 AbortSignal을 받습니다. cross-origin custom resolver를 사용할 때는 요청 헤더를 artifact origin으로 전달하지 않습니다.

공개 레퍼런스 탐색

const catalogue = createCatalogueClient({ endpoint: "https://scaffold.builders" });
const page = await catalogue.searchReferences("minimal store", { limit: 8 });
const ref = page.references[0]?.ref;
if (ref) {
  const detail = await catalogue.inspectReference(ref);
  const similar = await catalogue.similarReferences(ref, { by: "structure" });
}

이 세 메서드는 PAT를 전송하지 않으며, 검증된 작은 projection을 반환합니다. 검색 결과의 semanticIncomplete, hasMore, broaderStart를 보존합니다. 검색은 limit을 최대 100까지 늘릴 수 있고 유사 탐색은 nextCursor로 이어갑니다. 자료 다운로드는 기존 loadLayoutReference를 사용합니다. 공개 폴더는 listFolders({ visibility: "public" })로 조회합니다.