@01.works/reference-client

정적 portable manifest와 Design Context 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");

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

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

const { referenceBundle } = await loadLayoutReference("RUN_ID", {
  endpoint: "https://context.01.works",
});

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 연결과 구현 범위를 먼저 고정하고, global guide와 필요한 page 확장, 실제 selector/edge 대응, 최종 clean 화면 비교를 유지합니다. 보이는 control의 실제 목적지, 독립 상태, 모바일 workflow, skip/focus, 개발 overlay와 내부 clipping은 첫 제출 전에 직접 조작합니다. direct/derived 분류표나 장문의 gate별 PASS 보고서는 요구하지 않습니다.

정식 dogfood 완료는 복사 프롬프트를 받은 구현자와 별도의 세션이 cold review한 뒤에만 선언합니다. 첫 제출과 수정 후 결과는 구분해 보존하고, 개별 사이트에서 나온 결함 목록을 생성 프롬프트에 복제하지 않습니다.

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://context.01.works",
  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으로 전달하지 않습니다.