
Blockstudio 7.6에서는 프로젝트를 PHP에서 읽고 렌더링할 수 있으며, 프로덕션 프런트엔드 기본값을 `blockstudio.json`로 옮깁니다. 여기에는 인벤토리 API, 독립형 렌더링, 미디어 및 Tailwind용 템플릿 헬퍼, 성능 프로필, 단일 캐시 디렉터리, 조기 제공 기능을 갖춘 정적 사전 렌더링, 더 엄격한 분석 프리셋, 코딩 에이전트용 프로젝트 도구 생성이 포함됩니다.

두 가지 호출이 이번 릴리스의 핵심입니다. `Canvas::inventory()`는 프로젝트가 등록한 모든 페이지, 블록, 패턴, 사이트 편집기 템플릿, 템플릿 파트 및 번들 UI 예시를 반환합니다. `Render::document()`는 그중 무엇이든 렌더링에 사용된 에셋만 포함해 완성된 HTML를 반환합니다.

> **7.6.2 업데이트:** 파일 기반 페이지는 일반 WordPress 요청 중에 더 이상 조정되지 않습니다. 소스 변경 사항을 적용하려면 `wp bs pages sync`를 실행하거나 `Blockstudio\Pages::reconcile()`를 호출하세요. 컬렉션 경로 및 `templateFor` 기본값은 저장된 런타임 구성을 사용하며, 명시적 조정에서는 이전의 대규모 다국어 OR 메타 쿼리를 피합니다. 페이지 동기화가 더 이상 요청 훅에서 실행되지 않으므로 단기 `themeDefaults.syncPagesInDevelopment` 옵션이 제거되었습니다. `Pages::init()`는 이제 부트스트랩 전용입니다. `force`를 전달하던 통합 기능은 `Pages::reconcile()` 또는 CLI를 사용해야 합니다. Canvas를 열면 작성용 인벤토리를 위해 인증된 명시적 조정이 한 번 실행됩니다.

> **7.6.12 업데이트:** 이제 편집기 스타일시트는 에셋마다 SASS를 컴파일하는 대신 한 번의 재작성 과정에서 접두사가 추가되므로, 블록이 많은 사이트에서도 편집기를 처음 빌드할 때 적은 메모리 제한을 초과할 위험이 없습니다. 콘텐츠 해시가 적용된 Tailwind 스타일시트가 제거된 캐시된 사전 렌더링 페이지는 스타일이 적용되지 않은 채 제공되지 않고 다시 렌더링되며, PHP 캐시와 Early Serve 드롭인 모두에서 이 동작이 적용됩니다. 최상위 수준에 작성된 블록 속성은 버려지지 않고 렌더링 시 읽히므로, `WP_Block_Type`의 스키마 Blockstudio가 프로그램으로 데이터를 작성하는 도구에도 적용됩니다.

> **7.6.11 업데이트:** 이제 그래프 아티팩트를 설치할 때 저장소의 사본이 같은 키에서 변경된 경우 경로의 문서를 원자적으로 교체하고, 동일한 문서는 그대로 유지하며, 승격·교체·건너뜀·유지된 경로를 `Static_Prerender_Early_Serve::last_promotion()`을 통해 보고합니다.

> **7.6.10 업데이트:** 이제 런타임 캐시 적중 여부는 감시 디바운스 중에도 컴파일된 에셋이 제거되었는지 감지하며, 7.6 이전 버전의 플랫 런타임 캐시는 원자적으로 격리된 뒤 제한된 cron 배치로 삭제됩니다. 번들에 포함된 UI 전역 변수는 페이지마다 한 번만 출력됩니다. 그래프 모드 Early Serve는 배포된 경로 맵 외부의 라이브 렌더링 경로도 ID 캐시에서 제공할 수 있습니다. Tailwind는 콘텐츠 해시가 적용된 캐시 파일을 `tailwind.output: "link"`와 함께 출력하도록 설정할 수 있으며, 기본값은 인라인 출력입니다.

간단히 요약하면:

- **프로젝트 인벤토리**: `Canvas::inventory()`는 등록된 모든 레코드와 해당 소스, 안정적인 표시 순서를 반환합니다.
- **대상 지정 선택**: 블록과 페이지를 지정하면 탐색, 동기화, 렌더링 및 컴파일이 해당 레코드로 제한됩니다.
- **독립형 렌더링**: `Blockstudio\Render`는 블록, 구성 요소 또는 전체 문서에 대해 완성된 HTML를 반환합니다.
- **UI 구성 요소 패밀리**: `Blockstudio\Ui`는 번들 라이브러리를 구성 요소마다 하나의 공개 패밀리로 묶고, 각각에 예제를 제공합니다.
- **안정적인 이미지 크기**: `bs_media_image()`는 생성된 `assets/media.json`에서 실제 크기를 가져와 테마 에셋을 렌더링합니다.
- **Tailwind 클래스 도우미**: `bs_tw_merge()`와 `bs_tw_variants()`는 충돌을 고려해 병합하면서 PHP에서 클래스를 조합합니다.
- **성능 프로필**: `performance.profile`는 프로덕션 프런트엔드 기본값을 한 번에 활성화하며, 하위 값은 이를 재정의합니다.
- **형식 지정 설정 접근**: `Settings::get_bool()`와 관련 함수는 실제 형식으로 `blockstudio.json`를 읽고 파싱 오류를 표시합니다.
- **단일 캐시 디렉터리**: 생성된 모든 파일은 런타임 ID를 키로 사용해 `cache.path` 아래에 저장됩니다.
- **정적 사전 렌더링**: 익명 HTML를 캐시하고 종속성 그래프로 무효화할 수 있으며, WordPress이 부팅되기 전에 제공할 수 있습니다.
- **분석 프리셋**: `theme`, `extreme-theme`, `wordpress-render`는 블록 템플릿을 넘어 `blockstudio/phpstan`을 확장합니다.
- **관리형 커밋 훅**: `blockstudio-githooks sync`는 구성된 프리셋을 실행하는 pre-commit 훅을 작성하고 관리합니다.
- **프로젝트 계약**: `blockstudio-agents`는 프로젝트에서 작성하는 항목, 활성화된 기능, 프리셋에서 적용하는 규칙을 설명하는 `AGENTS.md`를 작성합니다.
- **문서 색인**: 이제 AI 컨텍스트 파일은 모든 문서와 각 문서의 목적, 관리하는 식별자의 색인입니다.
- **표준 블록 태그**: 독립형 명령어를 사용하면 접두사 및 별칭 축약형을 `<bs:namespace-slug>`로 바꿀 수 있으며, 실제 변경 전 미리 확인할 수 있습니다.
- **기본 호환성**: 위 기능은 `blockstudio.json`에서 명시하기 전까지 사이트를 변경하지 않습니다.

## 프로젝트 읽기 및 렌더링

### 프로젝트 인벤토리

`Canvas::inventory()`는 렌더링하지 않고 프로젝트가 등록한 모든 항목을 하나의 일반 배열로 반환합니다.

```php
use Blockstudio\Canvas;

$result = Canvas::inventory();

foreach ($result['inventory']['blocks'] as $block) {
    echo $block['name'] . "\n";
}
```

레코드는 형식별로 묶입니다: `pages`, `blocks`, `patterns`, `templates`, `parts`, `ui`. `order`은 모든 형식에 걸쳐 안정적인 표시 순서이며, `sources`은 각 레코드를 소스 경로에 연결하고, `warnings` 및 `errors`는 문제를 구조화된 항목으로 모읍니다.

블록 레코드에는 `id`, `name`, `title`, `source`, `path`, `provenance` 및 바로 렌더링할 수 있는 `declaration`이 포함됩니다. 페이지 레코드는 안정적인 ID로 `source`을, 렌더링을 수행하는 템플릿으로 `path`을 유지합니다.

### 대상 지정 선택

레코드를 지정하면 나중에 필터링하는 대신 작업 범위를 좁힙니다.

```php
$changed = Canvas::inventory([
    'blocks' => ['mytheme/hero'],
    'pages' => ['about'],
]);
```

그러면 블록 하나와 페이지 하나가 반환됩니다. `patterns`, `templates`, `parts`, `ui`은 빈 결과로 반환되며 해당 소스는 읽기, 동기화, 렌더링 또는 컴파일되지 않습니다.

규칙은 다음과 같이 정확히 적용됩니다.

- 형식 키가 하나도 없으면 모든 형식을 불러옵니다.
- `true`, `null` 또는 `"*"`를 지정하면 해당 형식의 모든 레코드를 불러옵니다.
- 문자열이나 목록은 ID, 이름, 슬러그, 경로 또는 소스 경로와 정확히 일치하는 항목을 찾습니다.
- 빈 문자열, 빈 목록 또는 `false`를 지정하면 해당 형식의 항목을 불러오지 않습니다.
- 형식 키를 하나라도 지정하면 생략된 형식은 그대로 둡니다.

더 이상 존재하지 않는 식별자는 오류 대신 `deleted`에 반환되며, Canvas REST 새로고침 엔드포인트도 `blocks` 및 `pages` 매개변수에 같은 규칙을 적용합니다.

`Canvas::documents()`는 동일한 선택을 적용하고 레코드마다 렌더링된 문서를 하나씩 추가합니다. 선택된 페이지는 복원된 프런트엔드 컨텍스트에서 렌더링되므로 쿼리 조건문, 본문 클래스, 단축 코드, 레이아웃, 리디렉션 및 등록 콜백은 페이지 렌더링을 요청한 요청이 아니라 해당 페이지를 기준으로 동작합니다.

### 독립형 렌더링

`Blockstudio\Render`는 프런트엔드와 동일한 파이프라인을 통해 렌더링된 HTML을 문자열로 반환합니다.

```php
use Blockstudio\Render;

$html = Render::composition([
    'root' => 'mytheme/card',
    'data' => ['heading' => 'Example card'],
    'layers' => [
        ['name' => 'mytheme/button', 'data' => ['label' => 'Continue']],
    ],
]);
```

기본이 되는 선언 형식은 하나이며 키 네 개를 사용합니다: `name`, `attributes`, `content`, `children`. `Render::normalize()`은 입력을 간편하게 하도록 `root`, `data`, `inner`, `innerBlocks`, `layers`, `example`를 이 형식에 통합합니다.
자식은 재귀적으로 렌더링되며 잘못된 입력에는 문제가 있는 블록 이름을 포함한 예외가 발생합니다.

`Render::document()`는 출력을 완전한 독립형 HTML 문서로 감쌉니다.

```php
$document = Render::document('mytheme/hero', [
    'title' => 'Hero preview',
]);

echo $document['html'];
```

`body`는 블록 출력만을, `html`은 조합된 문서를, `blocks`는 기여한 블록 이름을 반환하며, `assets`는 마크업을 `head`, `footer`, `styles`, `scripts`, `modules`, `interactivity`, `ui`, `tailwind`로 나눕니다.
에셋은 렌더링된 항목에만 적용되므로 편집기 전용 에셋은 포함되지 않습니다.

`Render::document_from_html()`는 다른 곳에서 렌더링된 HTML을 감싸고, `Render::content()`는 문서 없이 직렬화된 블록 콘텐츠를 렌더링합니다. 하나의 PHP 프로세스에서 문서 사이에 `Blockstudio\Batch_Render::reset()`를 호출하세요. `Canvas::documents()`는 이미 그렇게 합니다.

### UI 구성 요소 패밀리

`Blockstudio\Ui`는 번들에 포함된 UI 라이브러리를 내부 부분 목록이 아니라 공개 구성 요소마다 하나의 항목으로 제공합니다.

`Ui::inventory()`는 패밀리마다 루트 블록, 제목 및 필요한 구현 블록을 포함하는 항목을 하나씩 반환합니다. `Ui::examples()`는 각 패밀리에 결정적인 선언을 추가합니다. 기본값을 보존하고, 필수 자식 레이어를 상위 요소 안에 중첩하며, 필드가 비어 있을 때 사용할 안정적인 예시 텍스트를 지정합니다. 이 선언은 표준 형식이므로 바로 `Render::document()`에 입력할 수 있습니다.

Canvas에서도 같은 방식으로 그룹화됩니다. 번들에 포함된 UI는 `ui` 형식 아래에 패밀리마다 예제가 하나씩 표시되고, 구현 등록 항목은 `blocks`에 표시되지 않습니다.

각 패밀리는 조합에 맞게 설계되었습니다. 선택 상자는 다이얼로그 안에서 열리고 목록 상자는 트리거 위에 겹쳐 표시됩니다. 메뉴와 콤보 상자는 스크롤해도 유지되는 뷰포트 기준 고정 좌표를 사용합니다. 모달은 Escape를 한 번 누를 때마다 하나씩 쌓이고 닫히며, 모든 푸터는 동일한 닫기 컨트롤을 변형 옵션과 조합합니다. 이러한 연결 방식과 이를 유지하는 불변 조건은 [조합 장](https://blockstudio.dev/ko/ui/composition/)에서 설명하며, [/ui/examples](https://blockstudio.dev/ko/ui/examples/)에서 실제 조합 예제를 확인할 수 있습니다.

## 템플릿 도우미

### 안정적인 이미지 크기

`bs_media_image()`는 실제 너비와 높이, 예약된 가로 세로 비율을 사용해 테마 에셋을 렌더링하므로 미디어 라이브러리 외부의 이미지도 더 이상 레이아웃을 밀어내지 않습니다.

```php
<?php
echo bs_media_image([
    'src' => 'assets/images/hero.webp',
    'alt' => 'Hero',
]);
```

출력은 `figure.blockstudio-media`이며, 실제 `width`, `height`, `loading`, `decoding`을 담은 `img` 주위에 인라인 `aspect-ratio`이 적용됩니다. 크기는 생성된 `assets/media.json`에서 가져오며, 빌드 단계에서 `Blockstudio\Media_Metadata_Builder`이 작성하거나 직접 작성할 수 있습니다.

`src`는 테마 기준 상대 경로, 절대 경로 또는 전체 URL을 받으며, `attachmentId`는 미디어 라이브러리 이미지를 처리합니다. `eager`는 첫 화면 영역에서 지연 로딩을 비활성화하고, `sources`는 `<picture>`를 출력합니다.

`performance.media.lazy`를 활성화하면 실제 URL은 올바른 크기의 플레이스홀더 뒤에 `data-src`로 이동합니다.

### Tailwind 클래스 도우미

`bs_tw_merge()`와 `bs_tw_variants()`는 템플릿에서 Tailwind 클래스를 조합하며, 이때 엔진에 이미 포함된 Blockstudio를 PHP에서 사용합니다.

`bs_tw_merge('px-2 text-sm', 'px-4')`는 `text-sm px-4`을 반환합니다. 충돌하는 `px-2`는 제거되고 나중 값이 우선 적용됩니다. 중첩된 클래스 값 배열도 사용할 수 있습니다.

`bs_tw_variants()`는 구성 요소 변형에 사용할 수 있는 간단한 호출 가능 함수를 반환합니다.

```php
$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => ['sm' => 'h-8 px-3', 'lg' => 'h-12 px-6'],
    ],
    'defaultVariants' => ['size' => 'sm'],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);
```

출력 결과는 `inline-flex items-center h-12 px-6 rounded`입니다. 기본 클래스, 변형, 기본 변형, 복합 변형과 호출마다 지정하는 `class` 또는 `className`를 모두 지원합니다.

## 프로덕션 구성

### 성능 프로필

`performance.profile`는 한 곳에서 프로덕션 프런트엔드 기본값을 활성화합니다.

```json title="blockstudio.json"
{
  "performance": {
    "profile": "speed",
    "preload": {
      "links": "off"
    }
  }
}
```

`compat`가 기본값이며 아무것도 변경하지 않습니다. `speed` 및 `strict`는 동일한 항목을 활성화합니다. generator, emoji, feed, discovery 및 관련 게시물 출력을 head에서 제거하고, oEmbed 검색 및 호스트 스크립트를 제외하며, XML-RPC, pingback 및 원격 편집기 검색을 비활성화하고, 일반적인 core 프런트엔드 에셋을 제거하며, 이미지 출력 기본값을 적용합니다. 편집기 외부에서는 Heartbeat 빈도를 제한하고, 포인터를 올리거나 포커스할 때 동일 출처 문서를 미리 가져오며, Blockstudio의 이미지 로더를 사용합니다.

`preload.links`의 예처럼 모든 하위 값은 프로필을 재정의합니다. core 프런트엔드 에셋 제거는 먼저 테스트해야 합니다. 해당 에셋에 의존하는 페이지는 눈에 띄게 망가질 수 있기 때문입니다. `Runtime_Settings::current()`는 최종 적용된 프로필을 보여줍니다.

`themeDefaults`는 테마에서 직접 구현하던 두 가지 기능, 즉 `titleTag`과 업데이트 결과에서 활성 하위 테마 및 상위 테마를 숨기는 `suppressDirectoryUpdates`를 처리합니다.

### 형식 지정 설정 접근

`Blockstudio\Settings`는 JSON에 담긴 값을 그대로 반환하는 대신 올바른 형식으로 구성을 읽습니다.

```php
use Blockstudio\Settings;

$lazy = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);
$roles = Settings::get_array('users/roles');

foreach (Settings::errors() as $error) {
    error_log($error);
}
```

형식이 잘못된 JSON는 기본값으로 처리하는 대신 `Settings::errors()`를 통해 보고됩니다. `Settings::get_raw()`는 활성 소스에 선언된 항목만 반환하므로, 값이 `false`로 설정된 경우와 한 번도 설정되지 않은 경우를 구분할 수 있습니다.

`Settings::fingerprint()`는 현재 적용된 설정의 안정적인 ID를 반환하며, `blockstudio.json`가 변경되면 접근 시 설정을 다시 불러옵니다.

### 단일 캐시 디렉터리

이제 생성된 모든 파일은 `cache.path` 아래에 저장되며, 기본값은 `wp-content/blockstudio/cache`입니다.

```json title="blockstudio.json"
{
  "cache": {
    "enabled": true,
    "path": "cache/blockstudio"
  }
}
```

빌드 페이로드, 블록 등록 데이터, 편집기 에셋, 컴파일된 Tailwind CSS, 렌더링 문서, 아일랜드 조각, 정적 HTML, 그래프 색인, 워밍 큐 및 진단 정보가 모두 이 루트 아래에 저장됩니다. 상대 경로는 `WP_CONTENT_DIR`를 기준으로 해석되며, 절대 경로를 지정하면 전용 볼륨에 저장됩니다.

객체는 현재 네트워크와 사이트 아래에 저장되고, 그 아래 런타임 ID별로 분류됩니다. 런타임 ID는 Blockstudio, WordPress, PHP 버전, 적용된 설정, 활성 테마와 플러그인, 검색 소스 및 관련 소스 파일을 지문처럼 결합한 값입니다. 입력을 변경하면 영향을 받은 객체는 새 객체로 생성되며 기존 객체는 정리됩니다.

최초 빌드는 단일 실행으로 처리됩니다. 요청 하나가 빌드해 결과를 원자적으로 게시하는 동안 나머지 요청은 기다립니다. 새로고침에 실패해도 마지막 정상 객체를 계속 제공하며 실패 상태를 확인할 수 있고, `Blockstudio\Runtime_Cache::purge('tailwind')`는 범위 하나의 데이터를 지웁니다.

## 정적 사전 렌더링

정적 사전 렌더링은 완전한 익명 HTML 문서를 캐시하고 WordPress이 부팅되기 전에 제공할 수 있습니다. 기본적으로 꺼져 있습니다.

```json title="blockstudio.json"
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "earlyServe": true,
      "dynamicPaths": ["/account", "/checkout"]
    }
  }
}
```

### 적용 조건

완전한 익명 HTML 문서만 대상입니다. GET이 아닌 요청, 쿼리 문자열, 관리자 페이지, REST, Ajax, cron, 피드, 검색, 미리 보기, nonce가 포함된 요청, 개인화 쿠키가 있는 요청 및 `dynamicPaths` 아래의 모든 경로는 우회합니다.
응답에 `<!-- blockstudio:no-cache -->` 표시를 추가하면 캐시를 완전히 비활성화할 수 있습니다.

경로는 경계에 맞춰 일치하므로 `/account`는 `/account/orders`에 적용되지만 `/accounting`에는 적용되지 않습니다.

### 서명 및 그래프 모드

`invalidate`는 항목의 만료 방식을 결정합니다. 기본 `signature` 모드는 익명 요청에서 캐시가 없으면 ID를 키로 응답을 채우고 사이트 수준의 변경 이후 ID를 교체하므로 일반적인 사이트에 적합합니다.

`graph` 모드는 명시적인 빌드 및 배포 도구를 위한 것입니다. 각 페이지의 자체 소스 종속성을 기록하므로 계획을 실행하면 영향을 받은 URL만 다시 빌드합니다.

```php
use Blockstudio\Static_Prerender_Runtime;

$plan = Static_Prerender_Runtime::build_plan($sourceUrls);

foreach ($plan['affectedUrls'] as $url) {
    $result = render_with_dependencies($url);

    Static_Prerender_Runtime::persist_built_response(
        $url,
        $result['html'],
        $result['files'],
        $result['virtualHashes']
    );
}

Static_Prerender_Runtime::garbage_collect(array_keys($plan['live']));
```

### 조기 제공

`earlyServe`를 활성화하면 Blockstudio가 사이트별 경로 맵과 `advanced-cache.php` 드롭인을 관리합니다. 이 드롭인은 WordPress, 플러그인 또는 테마가 부팅되기 전에 조건에 맞는 캐시 적중 응답을 스트리밍합니다.

다른 곳에서 관리하는 맵, 드롭인 또는 `WP_CACHE` 선언은 덮어쓰지 않습니다. 그래프 아티팩트는 맵을 교체하기 전에 참조된 모든 HTML 파일이 유효한지 확인하므로, 렌더링이 완료되지 않은 배포에서도 이전 그래프가 계속 활성 상태로 유지됩니다. 멀티사이트 항목은 호스트, 홈 경로 및 사이트 ID별로 격리됩니다.

### 워밍 및 상태

일상적인 사용을 위한 WP-CLI 명령어 세 가지가 있습니다.

```bash
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
```

`status`는 활성 ID, 파일 및 바이트 수, 그래프 레코드, 큐 상태와 범위별 캐시 적중, 누락, 빌드 및 실패 횟수를 보고합니다.

## 분석 및 에이전트 도구

### 분석 프리셋

`blockstudio/phpstan`는 블록 분석에 세 가지 계층을 추가하고, 프로젝트에서 선택한 계층을 실행하는 명령어 하나도 제공합니다.

| 프리셋 | 추가 항목 |
| --- | --- |
| `base` | 기존 스키마, 템플릿, 훅, 설정 및 API 분석. |
| `theme` | 테마 루트, 스타일 헤더, 에셋, 선택자 범위 지정, 필드 기본값, 리피터 상한. |
| `extreme-theme` | PHPStan `max`, 안전하지 않은 PHP, 이스케이프 처리, Tailwind, JavaScript 및 Interactivity 검사. |
| `wordpress-render` | `extreme-theme`에 호출자가 제공하는 라이브 렌더링 프로브를 추가합니다. |

기본값은 `blockstudio.json`에서 가져오므로 대화형 실행, CI 및 커밋 훅이 동일한 구성을 공유합니다.

```json title="blockstudio.json"
{
  "phpstan": {
    "preset": "theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}
```

```bash
vendor/bin/blockstudio-phpstan --root . -- --no-progress
```

종료 코드는 통과 시 `0`, 진단 정보가 있을 때 `1`, 사용법이 잘못되었을 때 `2`입니다. 래퍼는 시스템 임시 디렉터리에서 구성을 조합하므로 생성된 구성, 기준선 또는 캐시가 프로젝트에 저장되지 않으며, PHPStan의 메모리 제한을 `1G`로 높입니다.

또한 BC Math 공급자가 포함되어 있어 JavaScript 검사에 더 이상 `ext-bcmath`이 필요하지 않습니다.

### 관리형 커밋 훅

설정 하나와 명령어 하나로 구성된 프리셋을 커밋 조건으로 적용할 수 있습니다.

```json title="blockstudio.json"
{
  "githooks": {
    "commit": true
  }
}
```

```bash
vendor/bin/blockstudio-githooks sync
```

동기화하면 Git의 공용 디렉터리에 훅과 소유권 기록을 작성하고, `core.hooksPath`을 관리형 디렉터리로 지정하며, 기존에 설정된 pre-commit 훅이 있으면 이를 이어서 실행합니다. 훅은 커밋 시점에 저장소와 프로젝트 루트를 찾으므로 연결된 체크아웃과 공백이 포함된 경로에서도 동작합니다.

이 훅은 `vendor/bin/blockstudio-phpstan`만 실행하며 파일을 포맷하거나 다시 작성하지 않습니다. `commit`을 `false`로 설정하고 다시 동기화하거나 `blockstudio-githooks remove`를 실행하면 기록된 훅 경로가 복원되고 Blockstudio에서 관리하는 파일만 삭제됩니다.

### 프로젝트 계약

`blockstudio-agents`는 블록 저장 위치, 이 프로젝트에서 페이지가 의미하는 것, 활성화된 기능 및 분석기에서 거부하는 항목을 명시하는 `AGENTS.md`를 작성합니다.

```bash
vendor/bin/blockstudio-agents
```

이 문서는 템플릿이 아니라 프로젝트에서 실제로 찾은 정보를 바탕으로 생성됩니다. `style.css` 헤더와 블록, 파일 기반 페이지가 있는 테마와 블록만 등록하는 플러그인에는 서로 다른 계약이 작성되며, 스캐너가 발견한 개수, 디렉터리, 네임스페이스 및 템플릿 언어가 포함됩니다. `blockstudio.json`에서 표시할 기능을 결정하므로 정적 사전 렌더링을 사용하지 않는 프로젝트에는 해당 내용이 언급되지 않습니다.

정확성 섹션은 선택된 프리셋 자체의 규칙 파일을 계층별로 읽으므로 프리셋에 규칙을 추가하면 그 프리셋을 사용하는 모든 계약이 변경됩니다.

소유권 관리는 커밋 훅과 같은 방식으로 작동합니다. 생성 표시가 없는 파일은 `--force`에서 달리 지정하지 않는 한 덮어쓰지 않고 거부합니다. 파일 끝에 있는 메모 영역은 다시 생성해도 유지됩니다. 계약이 최신 상태가 아니면 `--check`는 `1`로 종료되고, `--stdout`는 파일 시스템에 손대지 않고 계약 내용을 출력합니다.

### 문서 색인

이제 `blockstudio-llm.txt`는 문서를 이어 붙인 파일이 아니라 색인입니다. 게시된 각 문서는 섹션과 하위 섹션, 경로, 소스 파일, 한 줄짜리 목적 설명 및 관리하는 식별자와 함께 한 번씩 표시됩니다. 식별자에는 설정 경로, 훅 이름, PHP 함수와 클래스, 명령어가 포함됩니다.

```text
## Docs / Dev / Inspection Tools

### Canvas
route: /docs/dev/canvas
file: docs/docs/dev/canvas.md
purpose: A visual workspace and public inventory API for Blockstudio content.
settings: dev/canvas/enabled, ui
hooks: blockstudio/settings/dev/canvas/admin_bar, blockstudio/settings/dev/canvas/enabled
php: Blockstudio\Canvas, Canvas::documents(), Canvas::inventory()
```

에이전트는 색인을 읽고, 필요한 식별자를 소유한 문서 하나를 찾아 엽니다. 이전의 0.5MB짜리 연결 파일도 계속 생성되어 `/blockstudio-llm-full.txt`에 게시되지만, 이제 누구에게나 가장 먼저 제공되는 파일은 아닙니다.

## 표준 블록 태그

독립 실행형 명령은 접두사 및 별칭 약칭을 표준 `<bs:namespace-slug>` 표기로 다시 작성합니다. 이 표기는 실제 블록 이름을 기록하며 프로젝트 필터를 불러오지 않아도 확인할 수 있습니다.

`brand` 접두사는 `theme-components`에, `ui` 접두사는 `bsui`에 설정된 경우, 다음 약칭은:

```html
<brand-card>
  <ui-input />
</brand-card>
```

다음과 같은 의미입니다:

```html
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>
```

접두사와 정확한 별칭은 계속 사용할 수 있으며 더 이상 사용 중단 대상이 아닙니다. 이 명령은 WordPress을 불러오지 않으며 `--apply` 없이는 아무것도 쓰지 않습니다:

```bash
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/prefixes.json \
  --known-blocks=/tmp/blocks.json \
  --report=/tmp/tag-migration.json \
  --dry-run
```

`--prefix-map`은 각 접두사를 네임스페이스에 연결하고, `--known-blocks`은 등록된 블록 이름을 나열합니다. 보고서에는 이전 표기에서 표준 표기로의 매핑, 출현 횟수, 파일별 해시, 알 수 없는 태그·모호한 별칭·동적 태그의 별도 목록이 기록됩니다. `--apply`는 남아 있는 항목이 있으면 `--allow-unresolved`을 전달하지 않는 한 쓰기를 거부합니다.

PHP 문자열 안의 리터럴 태그를 포함해 쌍을 이루는 마크업, 중첩 마크업, 자체 닫는 마크업을 처리합니다. 태그 이름만 바뀌며, 두 번째 실행에서는 변경 사항이 없습니다. 주석, 코드 펜스, `<pre>` 또는 `<code>` 안의 예시는 보고서에만 표시됩니다.

## 기본 동작

7.6을 설치해도 그 자체로는 아무것도 바뀌지 않습니다.

**성능 프로필의 기본값은 `compat`입니다.** 헤드 출력, oEmbed, XML-RPC, Heartbeat, 이미지 기본값, 링크 미리 가져오기, 지연 로딩, 프런트엔드 `<title>`은 테마에서 설정한 WordPress 상태를 유지합니다.

**활성화하기 전까지는 다음 기능이 모두 꺼져 있습니다:** 모든 `performance.staticPrerender`, `performance.measurement`, `performance.media`, `themeDefaults` 키와 `githooks.commit`, `dev.canvas.enabled`, `ui.enabled`, `tailwind.enabled`, `blockTags.enabled`. 정적 사전 렌더링이 비활성화된 동안에는 파일을 쓰거나 드롭인 파일을 설치하지 않습니다.

**Canvas와 Render는 수동적으로 동작합니다.** 기존 레지스트리를 읽고 호출자가 요청한 항목만 렌더링합니다. 프런트엔드 출력에 후크를 연결하거나 경로를 등록하지 않습니다. Canvas 관리 화면을 사용하려면 여전히 `dev.canvas.enabled`과 `edit_posts`이 필요합니다.

**더 엄격한 분석을 사용하려면 명시적으로 지정해야 합니다.** `blockstudio/phpstan`을 설치해도 기본 확장 기능만 활성화되며, 프로젝트에서 프리셋을 지정하지 않으면 표준 명령은 `base`을 실행합니다.

**생성 파일은 해당 명령을 실행해야 만들어집니다.** `githooks.commit`은 `blockstudio-githooks sync`이 실행되기 전까지 아무 작업도 하지 않으며, `AGENTS.md`도 `blockstudio-agents`이 실행되기 전까지 동작하지 않습니다.

## 7.5에서 업그레이드

요구 사항은 동일합니다. PHP 8.2 이상, WordPress 6.7 이상입니다.

```bash
composer require blockstudio/blockstudio
```

**캐시는 한 번 다시 빌드됩니다.** 런타임 식별자에 Blockstudio 버전이 포함되므로 업그레이드 후 첫 요청은 캐시가 비어 있는 상태로 처리되고 오래된 객체는 정리됩니다. `wp-content/uploads/blockstudio/tailwind/cache` 아래에 있는 이전 Tailwind 캐시는 삭제해도 됩니다. 이 캐시를 glob으로 찾던 스니펫은 대신 `Blockstudio\Runtime_Cache::purge('tailwind')`을 호출해야 합니다.

7.6 이전의 평면형 `wp-content/blockstudio/cache/runtime` 디렉터리는 자동으로 활성 경로 밖으로 이름이 바뀌며, 제한된 WP-Cron 패스를 통해 제거됩니다. 따라서 배포 요청 중에 대규모 레거시 잠금 파일 트리를 삭제할 필요가 없습니다.

**생성 파일에는 관리 주체가 있습니다.** `assets/media.json`은 버전 관리에 포함하거나 빌드 단계에서 생성해야 합니다. 경로 맵, `advanced-cache.php` 드롭인 파일, `WP_CACHE` 선언은 `earlyServe`이 활성화된 동안에만 존재하고, 사전 커밋 후크는 동기화된 동안에만 존재합니다. 그 밖에 생성되는 항목은 모두 `cache.path` 아래에 저장되며 안전하게 삭제할 수 있습니다.

**삭제되거나 이름이 바뀐 항목은 없습니다.** `bs_render_block()`, `bs_block()`, `Blockstudio\Pages`, `Blockstudio\Patterns`은 파일 기반 콘텐츠의 표준 영역으로 계속 사용됩니다.

**기능별로 롤백할 수 있습니다.** `performance.profile`을 `compat`로, `staticPrerender.enabled`를 `false`로, `githooks.commit`를 `false`와 `sync`로, `cache.enabled`을 `false`로 되돌리면 각 변경 사항을 한 단계씩 취소할 수 있습니다.

권장 도입 순서:

1. `performance.profile`을 `speed`로 설정한 다음 헤드 출력, 피드, oEmbed 또는 XML-RPC에 의존하는 플러그인을 확인합니다.
2. `assets/media.json`을 생성하고 템플릿을 `bs_media_image()`로 옮긴 다음 `performance.media.lazy`을 켭니다.
3. `earlyServe`을 끈 상태로 `performance.staticPrerender`을 활성화합니다. `wp bs prerender status`으로 요청이 처리되는지 확인한 다음 `earlyServe`을 켭니다.
4. `blockstudio-phpstan --preset theme`을 실행해 오류가 없도록 정리한 다음 `githooks.commit` 뒤에 프리셋을 둡니다.

## 자세한 내용

- [Canvas](https://blockstudio.dev/ko/docs/dev/canvas/) 및 [목록과 문서 API](https://blockstudio.dev/ko/docs/dev/canvas/#public-inventory-and-document-api)
- [렌더링](https://blockstudio.dev/ko/docs/blocks/rendering/#structured-compositions-and-complete-documents), [UI 구성 요소](https://blockstudio.dev/ko/ui/#public-inventory-and-examples), [UI 구성](https://blockstudio.dev/ko/ui/composition/)
- [설정](https://blockstudio.dev/ko/docs/general/settings/) 및 [성능](https://blockstudio.dev/ko/docs/general/settings/#performance)
- [성능](https://blockstudio.dev/ko/docs/production/performance/), [캐싱](https://blockstudio.dev/ko/docs/production/caching/), [정적 사전 렌더링](https://blockstudio.dev/ko/docs/production/static-prerendering/)
- [Tailwind CSS](https://blockstudio.dev/ko/docs/tailwind/#template-composition-helpers)
- [PHPStan](https://blockstudio.dev/ko/docs/dev/phpstan/): [프리셋](https://blockstudio.dev/ko/docs/dev/phpstan/#analysis-presets), [표준 명령](https://blockstudio.dev/ko/docs/dev/phpstan/#canonical-command), [관리형 커밋 후크](https://blockstudio.dev/ko/docs/dev/phpstan/#managed-commit-hook), [프로젝트 계약](https://blockstudio.dev/ko/docs/dev/phpstan/#project-contract-for-coding-agents)
- [AI 통합](https://blockstudio.dev/ko/docs/dev/ai/): 문서 색인 및 전체 텍스트
- [마이그레이션](https://blockstudio.dev/ko/docs/dev/migration/v7/#canonical-block-tags) 및 [PHP 후크](https://blockstudio.dev/ko/docs/blocks/hooks/php/)
