본문으로 건너뛰기

Dennis · 2026년 7월 27일

Blockstudio 7.6

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를 한 번 누를 때마다 하나씩 쌓이고 닫히며, 모든 푸터는 동일한 닫기 컨트롤을 변형 옵션과 조합합니다. 이러한 연결 방식과 이를 유지하는 불변 조건은 조합 장에서 설명하며, /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
{
  "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
{
  "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
{
  "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 명령어 세 가지가 있습니다.

셸
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
{
  "phpstan": {
    "preset": "theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}
셸
vendor/bin/blockstudio-phpstan --root . -- --no-progress

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

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

관리형 커밋 훅

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

JSON
{
  "githooks": {
    "commit": true
  }
}
셸
vendor/bin/blockstudio-githooks sync

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

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

프로젝트 계약

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

셸
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 없이는 아무것도 쓰지 않습니다:

셸
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 이상입니다.

셸
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 뒤에 프리셋을 둡니다.

자세한 내용