{"_id":"@01.works/reference-contracts","_rev":"3-7ad3c98cc06ceddcad4608b9da27fbcd","name":"@01.works/reference-contracts","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@01.works/reference-contracts","version":"0.1.0","keywords":["layout","archive","contracts","schema","typescript"],"license":"MIT","_id":"@01.works/reference-contracts@0.1.0","maintainers":[{"name":"kdnhyk","email":"kdnhyk@gmail.com"}],"homepage":"https://github.com/01-office/design-context/tree/main/packages/reference-contracts#readme","bugs":{"url":"https://github.com/01-office/design-context/issues"},"dist":{"shasum":"0ca49225f877761e8e3f38848dd77a48ce17d467","tarball":"https://registry.npmjs.org/@01.works/reference-contracts/-/reference-contracts-0.1.0.tgz","fileCount":9,"integrity":"sha512-koYnaVRKDuiipQ322I1/ukyAV3TnVbOmtMwZ7Hoj0vLSSbrRGJrtExui4fjod4+o8Rxi6ptF0WK14/0bISszAg==","signatures":[{"sig":"MEYCIQC+bGyN6D2rh8X+Mleep81dkMnjv5q55/KHmmBBFQaDXAIhAIr/Ap7I21IFrKulyfWHRoI6qkPi+GLj+9UbdpjIZgll","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":97768},"type":"module","_from":"file:01.works-reference-contracts-0.1.0.tgz","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./src/index.ts","import":"./src/runtime.mjs","default":"./src/runtime.mjs"},"./catalogue":{"types":"./src/catalogue.ts","import":"./src/catalogue.mjs","default":"./src/catalogue.mjs"},"./schemas/layout-map.json":"./schemas/layout-map.schema.json","./schemas/layout-package.json":"./schemas/layout-package.schema.json"},"scripts":{"test":"node test/runtime.test.mjs","test:all":"pnpm run test && pnpm run test:package","typecheck":"node --check src/runtime.mjs && tsc --noEmit","lint:package":"publint","test:package":"node test/package-smoke.test.mjs"},"_npmUser":{"name":"kdnhyk","email":"kdnhyk@gmail.com"},"_resolved":"/private/var/folders/mr/1yy73dlx7rg_sb0x6j2hvfs80000gn/T/9724ed568653ec600994ac34d634fdf6/01.works-reference-contracts-0.1.0.tgz","_integrity":"sha512-koYnaVRKDuiipQ322I1/ukyAV3TnVbOmtMwZ7Hoj0vLSSbrRGJrtExui4fjod4+o8Rxi6ptF0WK14/0bISszAg==","repository":{"url":"git+https://github.com/01-office/design-context.git","type":"git","directory":"packages/reference-contracts"},"_npmVersion":"11.16.0","description":"Portable runtime and TypeScript contracts for Design Context reference packages","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"publint":"^0.3.23","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/reference-contracts_0.1.0_1787907882751_0.3047829088968945","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@01.works/reference-contracts","version":"0.2.0","keywords":["layout","reference","contracts","schema","typescript"],"license":"SEE LICENSE IN LICENSE","_id":"@01.works/reference-contracts@0.2.0","maintainers":[{"name":"kdnhyk","email":"kdnhyk@gmail.com"}],"homepage":"https://github.com/01-office/design-context/tree/main/packages/reference-contracts#readme","bugs":{"url":"https://github.com/01-office/design-context/issues"},"dist":{"shasum":"ce61fefcf368ce8decb9f77623cfde626fac21a5","tarball":"https://registry.npmjs.org/@01.works/reference-contracts/-/reference-contracts-0.2.0.tgz","fileCount":9,"integrity":"sha512-dDnn5GnBiQWLVQ1WFKVOqH6Xq/XgxzCB6eCPKcJjfY4LVcIcAow5KbdWYjW88kr74iHAyChkIs36UubxJn2ShQ==","signatures":[{"sig":"MEQCIGrhWMW83If7IfszUlty5wTOc9I9Lq7HLBChjltzJ7DgAiAgFV1fwCEG4n83ijqaJFcLRqNARH1MCfDXdzUVijlIQg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":128994},"type":"module","_from":"file:/home/runner/work/_temp/npm-release-33478590266-1.tgz","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./src/index.ts","import":"./src/runtime.mjs","default":"./src/runtime.mjs"},"./catalogue":{"types":"./src/catalogue.ts","import":"./src/catalogue.mjs","default":"./src/catalogue.mjs"},"./schemas/layout-map.json":"./schemas/layout-map.schema.json","./schemas/layout-package.json":"./schemas/layout-package.schema.json"},"scripts":{"test":"node test/runtime.test.mjs","test:all":"pnpm run test && pnpm run test:package","typecheck":"node --check src/runtime.mjs && tsc --noEmit","lint:package":"publint","test:package":"node test/package-smoke.test.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ea8c1e61-b7f1-45b3-864e-59d1263224fb"}},"_resolved":"/home/runner/work/_temp/npm-release-33478590266-1.tgz","_integrity":"sha512-dDnn5GnBiQWLVQ1WFKVOqH6Xq/XgxzCB6eCPKcJjfY4LVcIcAow5KbdWYjW88kr74iHAyChkIs36UubxJn2ShQ==","repository":{"url":"git+https://github.com/01-office/design-context.git","type":"git","directory":"packages/reference-contracts"},"_npmVersion":"11.17.0","description":"Portable runtime and TypeScript contracts for Design Context reference packages","directories":{},"_nodeVersion":"24.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"publint":"^0.3.23","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/reference-contracts_0.2.0_1788245160910_0.1773495451850171","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@01.works/reference-contracts","version":"0.3.0","description":"Portable runtime and TypeScript contracts for Design Context reference packages","type":"module","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./src/index.ts","import":"./src/runtime.mjs","default":"./src/runtime.mjs"},"./catalogue":{"types":"./src/catalogue.ts","import":"./src/catalogue.mjs","default":"./src/catalogue.mjs"},"./schemas/layout-package.json":"./schemas/layout-package.schema.json","./schemas/layout-map.json":"./schemas/layout-map.schema.json","./schemas/visual-tile-set.json":"./schemas/visual-tile-set.schema.json"},"devDependencies":{"publint":"^0.3.23","typescript":"^5.9.3"},"repository":{"type":"git","url":"git+https://github.com/01-office/design-context.git","directory":"packages/reference-contracts"},"bugs":{"url":"https://github.com/01-office/design-context/issues"},"homepage":"https://github.com/01-office/design-context/tree/main/packages/reference-contracts#readme","keywords":["layout","reference","contracts","schema","typescript"],"publishConfig":{"access":"public"},"license":"SEE LICENSE IN LICENSE","scripts":{"test":"node test/runtime.test.mjs","test:package":"node test/package-smoke.test.mjs","test:all":"pnpm run test && pnpm run test:package","typecheck":"node --check src/runtime.mjs && tsc --noEmit","lint:package":"publint"},"_id":"@01.works/reference-contracts@0.3.0","_integrity":"sha512-qLxsL+CJj5ymusQW9ktIuiwpjLvM+53o8I1HH+mobAiW2/FIfOcFaDDSzAYTXOk3Hm4i4Bv5sAb0s8urXPWw1g==","_resolved":"/home/runner/work/_temp/npm-release-33957311116-1.tgz","_from":"file:/home/runner/work/_temp/npm-release-33957311116-1.tgz","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-qLxsL+CJj5ymusQW9ktIuiwpjLvM+53o8I1HH+mobAiW2/FIfOcFaDDSzAYTXOk3Hm4i4Bv5sAb0s8urXPWw1g==","shasum":"b27a0ff3ced38993e2f37e7258f6895ceefed82f","tarball":"https://registry.npmjs.org/@01.works/reference-contracts/-/reference-contracts-0.3.0.tgz","fileCount":10,"unpackedSize":157409,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCQN4MSooRbAJNqTr/R636Rr7W0GDf8r8FP65lIiCLcRwIhAIHjHfhh4AxGiFjR2Ah3iVGV52avVRsZm2OSgJywfG2s"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ea8c1e61-b7f1-45b3-864e-59d1263224fb"}},"directories":{},"maintainers":[{"name":"kdnhyk","email":"kdnhyk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/reference-contracts_0.3.0_1788599551964_0.007716422914531451"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T09:04:42.564Z","modified":"2026-09-05T09:12:32.290Z","0.1.0":"2026-08-28T09:04:42.889Z","0.2.0":"2026-09-01T06:46:01.043Z","0.3.0":"2026-09-05T09:12:32.139Z"},"bugs":{"url":"https://github.com/01-office/design-context/issues"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/01-office/design-context/tree/main/packages/reference-contracts#readme","keywords":["layout","reference","contracts","schema","typescript"],"repository":{"type":"git","url":"git+https://github.com/01-office/design-context.git","directory":"packages/reference-contracts"},"description":"Portable runtime and TypeScript contracts for Design Context reference packages","maintainers":[{"name":"kdnhyk","email":"kdnhyk@gmail.com"}],"readme":"# `@01.works/reference-contracts`\n\nDesign Context API, catalogue, collector가 공유하는 공개 API DTO와 portable layout\nmanifest의 런타임 계약 패키지입니다.\n\n```sh\npnpm add @01.works/reference-contracts\n```\n\n- DB row, Worker binding, HTTP client 구현은 포함하지 않습니다.\n- manifest TypeScript 타입, runtime validator, canonical JSON Schema와\n  schema/extractor version, quality flag 분류를 한 곳에서 제공합니다.\n- 런타임 dependency와 코드 생성 단계가 없습니다.\n- 공개 응답 필드를 변경할 때 서버 반환 타입과 catalogue 사용처를 함께 검사합니다.\n\n`validateManifest()`, `validateLayoutMap()`, `validateSemanticEvidence()`는 지원한다고 명시한 버전만 받아들이며,\n`matchesArtifactSignature()`는 artifact kind별 MIME과 최소 파일 signature·container 구조가\n일치하는지 검사합니다. 이 검사는 손상된 header, 누락된 payload 같은 명백한 불일치를\n거르는 ingest gate이며 CRC 검증이나 이미지의 완전한 decode 가능성을 보장하지 않습니다.\n`LayoutManifest`와 `LayoutAnalysisMap`은 검증 후 값의 TypeScript 표현입니다.\nportable 구조를 검사하는 JSON Schema는 `@01.works/reference-contracts/schemas/layout-package.json`,\n`@01.works/reference-contracts/schemas/layout-map.json`,\n`@01.works/reference-contracts/schemas/visual-tile-set.json` subpath로 제공합니다.\n선택적 `metadata.classification`은 사이트 전체가 아니라 현재 대표 capture의 분류이며\n`version`, 정확히 하나의 `categories`, 대표 screenshot의 `evidenceSha256`,\n`classifiedAt`만 저장합니다.\n카테고리는 페이지의 지배적인 표현 방식 하나이며 배열은 저장 형식 호환을 위해서만 유지합니다.\n미분류는 별도 enum이 아니라 classification 부재로 표현합니다.\nJSON Schema로 직접 표현할 수 없는 cross-field 의미 규칙인 region ID 고유성과\n`extraction.emitted_regions === regions.length`, classification evidence와 대표 screenshot의\nchecksum 일치는 runtime validator가 추가로 검사합니다.\nJSON Schema의 `format`은 validator 설정에 따라 annotation으로만 처리될 수 있으므로,\nURL을 실제로 수락하는 경계에서는 `validateManifest()`를 호출해야 합니다. 런타임 validator는\noptional URL의 `null`을 허용하되 필수 `requestedUrl`은 parse 가능한 HTTP(S) 문자열만 받습니다.\n저장 계약의 URL은 `new URL(input).href`와 같은 canonical form이어야 합니다. 사용자 입력을\n받는 호출자는 contract 검증 전에 별도로 정규화하며 validator 자체는 noncanonical URL을\n암묵적으로 고쳐 저장하지 않습니다.\n\n## Artifact 신뢰 경계\n\n- collector가 새 package를 만들 때 screenshot은 선택적 full-page preview와 preview/thumbnail 생성 과정에서 Sharp로\n  decode되며, 파생 WebP의 실제 dimensions도 Sharp metadata로 확인합니다.\n- `validatePackage()`는 manifest/layout-map 의미, regular-file·symlink 경계, 크기, hash와\n  최소 signature를 검사합니다. PNG/JPEG/GIF/WebP header dimensions와 descriptor,\n  layout-map과 viewport, wireframe SVG root와 map document dimensions도 비교하지만 모든\n  raster pixel이나 region별 wireframe geometry를 다시 decode·비교하지는 않습니다.\n- Design Context API ingest는 scoped uploader를 신뢰 경계로 두고 크기, hash, 선언 MIME과\n  동일한 최소 cross-artifact 비교를 수행합니다. 임의 media를 완전한 decoder로 정화하는\n  API가 아닙니다. dimension parser가 없는 AVIF는 0.4 captured raster artifact에서 허용하지\n  않으며, favicon과 0.3 호환 artifact에서는 signature gate만 적용합니다.\n\nExtractor 0.7 captured package는 positive document dimensions, responsive rendition과\n표현 구조 측정값을 포함한 semantic evidence JSON artifact가 필수입니다. 0.7.1은 여기에\ncapture environment/semantic consistency 관측과 extraction coverage를 추가합니다. 이 요구는\n버전 문자열 비교가 아니라 `EXTRACTOR_CONTRACTS`의 `requireCaptureObservations`와\n`requireExtractionCoverage` capability로 dispatch합니다. 0.5는 같은 responsive image 계약을\nsemantic artifact 없이 유지하고, 0.4는 screenshot/preview/thumbnail descriptor dimensions를 요구합니다.\n0.3 호환 package는 해당 dimension fields가 존재할 때만 header와 비교합니다. layout-map과\nwireframe의 viewport/document consistency는 모든 지원 버전에 적용됩니다.\n\n`VisualTileSet`은 완전한 document coverage를 가진 PNG 타일 묶음의 독립 transport 계약입니다.\n각 타일은 document CSS 좌표와 원본 DPR의 bitmap dimensions, portable path, bytes, checksum을\n기록합니다. runtime validator는 타일 순서·경계·경로 중복·bitmap dimensions와 2차원 전체 coverage를\n검사합니다. 안정성·seam·resource readiness는 transport 바깥의 quality 판정으로 유지합니다.\n이 계약은 아직 manifest extractorVersion이나 API publication capability를 승격하지 않습니다.\n\n`LayoutReferenceBundle`은 `/v1/layouts/:id/reference`의 read-only 응답 타입입니다.\n`LayoutDetail`과 절대 resource URL만 묶으며 구현 지시, 코멘트, write-back 상태는\n포함하지 않습니다. 현재 reference schema version은 `1.0`, kind는\n`layout-reference`입니다.\n\nCatalogue 전용 폴더·사용자·제출 DTO는 core reference 계약과 release surface를 분리한\n`@01.works/reference-contracts/catalogue` subpath에서 제공합니다. 폴더 API는 목록용\n`CatalogueFolderSummary`, 항목 페이지용 `CatalogueFolderItemPage`, 항목 추가 결과용\n`CatalogueFolderItemMutationResult`를 구분합니다.\n\nAgent setup prompt와 제품별 orchestration 정책은 이 계약 패키지에 포함하지 않습니다.\n프레임워크 비종속 prompt compiler와 workflow readiness는\n`@01.works/reference-client`가 소유하며, Catalogue 앱도 같은 공개 API를 사용합니다.\n\n## 0.2에서 0.3으로 이전\n\n0.3은 compact `LayoutCardViewportAssets`에 `overlayAvailable`을 추가합니다. 합성된\n`overlayUrl`은 artifact 존재 여부와 무관하게 제공될 수 있으므로, 현재 viewport에서\n오버레이 수정이 가능한지는 URL truthiness가 아니라 이 boolean으로 판정해야 합니다.\n`LayoutRun`과 `LayoutDetail`에서는 기존처럼 `artifacts`의 `layoutMap` 또는 `overlay`가\nauthoritative signal입니다.\n\n## 0.1에서 0.2로 이전\n\n0.2는 1.0 이전 계약을 정리하는 breaking release입니다. 소비자는 정확한 버전을 고정하고 다음\n변경을 함께 적용합니다.\n\n- `LayoutRun.category`는 `categories`로 바뀌었으며 공개 응답에서는 `[]` 또는 정확히 한 값입니다.\n- manifest의 `metadata.classification.category`는 저장 형식 호환을 위한 단일 원소\n  `categories` tuple로 바뀌었습니다.\n- category ID는 `collection | overview | showcase | sequence | visualization | workspace | scene`으로\n  교체되었습니다. 0.1 ID를 새 ID로 추측 변환하지 말고 미분류로 되돌린 뒤 필요할 때 다시 판정합니다.\n- current extractor는 0.7이며 0.3, 0.4, 0.5 package를 읽기 호환합니다. 0.7 captured viewport는\n  responsive rendition과 `semanticEvidence`가 필요합니다.\n- `CatalogueSiteReference.id`는 항상 존재합니다. 폴더 항목 수정·삭제·정렬에는 URL이나 layout ID가\n  아니라 이 item ID를 사용합니다.\n- `LayoutRun.renditions`가 production DTO와 동일하게 공개 타입에 포함됩니다.\n- reference bundle은 `complete`, 양 viewport `captured`, 빈 readiness reason, extractor별 필수\n  artifact를 만족하는 agent-ready snapshot입니다.\n- `artifactCount`/`artifactBytes`는 저장된 전체 artifact 합계이므로 공개 `artifacts` 배열에는\n  equality가 아니라 하한 관계를 보장합니다.\n- 공식 catalogue URL은 `/layouts/:id`입니다. 0.1의 `/?layout=:id`는 client 입력 호환 목적으로만\n  계속 읽습니다.\n\nVisual composition taxonomy는 제품의 공개 reference 계약이 아니라 비공개 사례 연구입니다.\n`@01.works/reference-contracts`는 해당 registry나 enum을 export하지 않습니다.\n","readmeFilename":"README.md"}