
Blockstudio 7.2 expande o framework em duas frentes ao mesmo tempo.

A primeira é **visibilidade e fluxo de trabalho** dentro de um único projeto: uma nova visão geral administrativa, um navegador de banco de dados, um navegador do registro administrativo e prelúdios SCSS para configurações compartilhadas de Sass.

A segunda é **o ecossistema em torno de Blockstudio**: um registro CLI para distribuir blocos (como shadcn para WordPress) e uma extensão PHPStan que traz segurança de tipos no estilo TypeScript para templates, tags de bloco, `db.php`, `rpc.php`, `cron.php` e os arquivos de esquema relacionados.

As duas frentes têm o mesmo objetivo: facilitar o entendimento, a evolução e o compartilhamento de projetos maiores de Blockstudio.

## Experiência administrativa

Duas adições facilitam a navegação de projetos maiores no wp-admin.

### Visão geral administrativa

Agora, Blockstudio inclui uma tela administrativa em **Ferramentas > Blockstudio**. Ela oferece um só lugar para inspecionar o que o sistema registrou a partir do sistema de arquivos.

A visão geral inclui abas dedicadas a:

- Blocos
- Extensões
- Campos
- Páginas
- Esquemas

Além dessa visão geral, a área administrativa agora inclui uma seção dedicada a **Bancos de dados**. Ela lista todos os esquemas `Blockstudio\Db` registrados e permite inspecionar registros reais diretamente no wp-admin.

Em vez de criar uma grade personalizada de painéis, a tela usa tabelas DataViews nativas do WordPress. Assim, a UI fica alinhada ao wp-admin e continua prática mesmo quando um projeto tem dezenas ou centenas de registros.

Em uma instalação pequena, você consegue manter na cabeça o estado de execução. Em uma base de código maior, isso deixa de funcionar. Surgem perguntas como:

- Quais blocos estão realmente registrados agora?
- Quais extensões se aplicam a `core/*` e quais se aplicam a blocos individuais?
- Quais páginas estão sincronizadas e a quais tipos de publicação pertencem?
- Quais campos reutilizáveis existem neste projeto?
- Quais esquemas estão registrados e qual backend de armazenamento eles usam?

Até agora, a resposta exigia alguma combinação de examinar pastas, abrir arquivos JSON e percorrer PHP. A visão geral transforma isso em uma interface administrativa concreta.

Cada aba foi criada para responder a perguntas diferentes:

- **Blocos** mostra os tipos de bloco registrados, o modo de renderização, a versão API e a contagem de atributos
- **Extensões** mostra os blocos aos quais se aplicam, além da prioridade e dos detalhes de renderização
- **Campos** oferece um inventário rápido das definições reutilizáveis de campos personalizados
- **Páginas** mostra páginas sincronizadas baseadas em arquivos, com tipo de publicação, status, mecanismo de template e estado da sincronização
- **Esquemas** apresenta os esquemas de armazenamento registrados, com backend, quantidade de campos e escopo de capacidade

O navegador do banco de dados é mantido intencionalmente separado da carga inicial da visão geral. Em vez de serializar todas as linhas ao carregar a página, ele apenas localiza os esquemas disponíveis de início e busca os registros sob demanda quando você abre uma aba do banco de dados. Assim, a área administrativa continua útil mesmo quando um projeto tem conjuntos de dados maiores por trás de `db.php`.

Esta primeira versão é intencionalmente voltada para registros vinculados a esquemas. Não é uma página de configurações. É uma página de inspeção.

Se não quiser usar esse recurso, desative-o por completo:

```php
add_filter('blockstudio/admin/enabled', '__return_false');
```

### Navegador do registro administrativo

Ao lado da visão geral, há uma segunda aba: **Registro**. Ela permite navegar pelos registros remotos de blocos configurados no `blocks.json` do seu tema e importar blocos diretamente do painel administrativo do WordPress sem tocar em um CLI.

```json title="blocks.json"
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

O navegador consulta cada registro configurado, lista todos os blocos disponíveis e mostra se já estão instalados localmente ou se podem ser importados. Cada linha tem um botão Importar que baixa os arquivos do bloco para o diretório configurado do seu tema. Para os blocos já instalados, aparece um botão Reimportar.

Há suporte a registros autenticados usando o formato de objeto com `headers`, incluindo interpolação de `${ENV_VAR}` para que os tokens nunca sejam incluídos no controle de versão.

Isso torna a navegação e o uso de registros uma experiência administrativa integrada, em vez de apenas um fluxo de trabalho de CLI.

## Registro CLI

A outra parte da história dos registros é um CLI independente: `blockstudio/registry`.

É uma ferramenta no estilo shadcn para blocos WordPress. Sem pacote npm, sem etapa de compilação. Você executa um comando, o código-fonte do bloco é copiado para o seu projeto e passa a ser totalmente seu.

```bash
npx blockstudio init
npx blockstudio add ui/tabs
```

O CLI funciona com qualquer tipo de bloco: blocos Blockstudio, saída `@wordpress/create-block`, blocos PHP simples. O registro não se importa com o conteúdo da pasta. Ele lê o manifesto de arquivos de `registry.json` e copia exatamente esses arquivos.

Os autores de blocos publicam um `registry.json` em qualquer URL (conteúdo bruto de GitHub, S3, um servidor personalizado) que lista os blocos disponíveis, com metadados, dependências e listas de arquivos. Os usuários adicionam o URL ao seu `blocks.json` e obtêm blocos pelo nome.

O CLI oferece suporte a:

- **Resolução de dependências**: os blocos podem declarar dependências de outros blocos, resolvidas automaticamente com detecção de ciclos
- **Tratamento de conflitos entre vários registros**: quando o mesmo nome de bloco existe em vários registros, o CLI pede que você escolha um
- **Registros autenticados**: tokens bearer, autenticação básica e cabeçalhos personalizados com interpolação de variáveis de ambiente
- **TUI interativa**: criada com Ink, com indicadores de atividade, prompts de seleção e indicadores de progresso
- **Modo não interativo**: sinalizador `--yes` e fallback automático para CI/entrada redirecionada por pipe
- **Pesquisa e listagem**: navegue pelos registros na linha de comando

O pacote inclui testes 130 que abrangem esquemas, resolução de dependências, busca de HTTP, gravação de arquivos, todos os fluxos de comandos e a UI interativa do Ink.

Documentação completa em [blockstudio.dev/registry](https://blockstudio.dev/pt/registry/).

## Extensão PHPStan

A outra grande novidade é `blockstudio/phpstan`: uma extensão de PHPStan que oferece aos usuários do Blockstudio a segurança de tipos que os desenvolvedores TypeScript esperam.

```bash
composer require --dev blockstudio/phpstan
```

A extensão lê os esquemas reais do seu projeto durante a análise e fornece os tipos resultantes ao PHPStan. Agora, isso abrange templates PHP, Twig, Blade, tags de bloco, registros de banco de dados tipados, caminhos de configurações, nomes de hooks e validação de esquemas em `block.json`, `field.json`, JSON de extensão, `page.json`, `db.php`, `rpc.php`, `cron.php` e `blockstudio.json`.

### Templates de bloco com segurança de tipos

Os acessos a campos em `$a` são validados em relação ao `block.json` correspondente:

```php title="blockstudio/hero/index.php"
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
```

### Registros de banco de dados com segurança de tipos

`Db::get()` retorna uma instância tipada com base no seu esquema `db.php`. A estrutura do registro é criada a partir dos campos reais:

```php title="db.php"
return [
  'storage' => 'table',
  'fields' => [
    'email' => ['type' => 'string', 'required' => true],
    'name'  => ['type' => 'string'],
  ],
];
```

```php
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
```

### Validação de esquemas

Arquivos de esquema inválidos são detectados durante a análise: `block.json`, `field.json`, JSON de extensão, `page.json`, `db.php`, `rpc.php`, `cron.php` e `blockstudio.json`. Nomes ausentes, tipos de campo incorretos, definições malformadas e valores booleanos abreviados obsoletos (`"tailwind": true` em vez do objeto aninhado) são todos informados com a linha exata no arquivo de origem.

### Validação de caminhos de configurações

As chamadas `Settings::get()` são validadas em relação ao esquema de configurações conhecido:

```php
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
```

### Validação de nomes de hooks

O mesmo vale para os nomes de hooks de filtro e de ação:

```php
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
```

A extensão também inclui stubs para toda a Blockstudio API pública do `Db`: `Settings`, `Field_Registry`, `Build` e funções auxiliares globais. Você tem preenchimento automático e verificação de tipos para todas as APIs do Blockstudio sem precisar do código-fonte do plugin na sua máquina de desenvolvimento.

## Facilidades para autoria

Duas pequenas facilidades para autoria completam esta versão.

### Prelúdios globais de SCSS

Blockstudio já oferecia compilação de SCSS, mas havia um ponto de atrito incômodo: a configuração compartilhada de Sass.

Se você quisesse acessar um conjunto comum de variáveis, funções ou mixins, precisava importá-los em cada arquivo SCSS. Isso logo se torna repetitivo, especialmente em sistemas de design maiores ou em toolkits Sass como Bootstrap.

A versão 7.2 adiciona um hook de prelúdio para resolver exatamente isso:

```php
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

Combinado com o filtro `blockstudio/assets/process/scss/import_paths` já existente, você define uma interface compartilhada de Sass uma única vez, e ela fica disponível para todos os arquivos compilados.

Assim, a folha de estilos de um bloco pode se concentrar nos estilos de que realmente precisa:

```scss title="style.scss"
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}
```

Sem importações repetidas em cada recurso do bloco. Não é um "suporte a Bootstrap" em um modo especial. É um hook genérico para compartilhar Sass em um projeto, seja isso fornecido por Bootstrap ou pelo seu próprio toolkit interno.

### Definições de API de blocos nativas de PHP

A versão 7.2 também adiciona uma sintaxe opcional nativa de PHP para as APIs full-stack de blocos. Os arrays continuam sendo o padrão e têm suporte completo. Nada foi substituído. Mas, se você prefere argumentos nomeados, enums e atributos a arrays de configuração aninhados, agora pode optar por esse estilo.

Para `rpc.php`, retorne um objeto com métodos atribuídos:

```php title="rpc.php"
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};
```

Para `cron.php`, a mesma ideia funciona com `#[Cron]`:

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};
```

E, para `db.php`, agora há uma pequena camada de construção:

```php title="db.php"
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);
```

Isso oferece um equilíbrio melhor para bases de código maiores. Você mantém a simplicidade do formato de array quando quiser e pode mudar para uma interface de PHP mais fácil de explorar quando um bloco passa a ter mais do que alguns campos ou endpoints.

## Por que esses recursos são lançados juntos

A visão geral administrativa, o navegador de registros, o CLI de registros e a extensão PHPStan respondem à mesma pergunta: como manter um projeto Blockstudio compreensível à medida que ele cresce?

As ferramentas administrativas respondem a essa pergunta no nível do projeto: visibilidade do que está registrado, possibilidade de obter blocos dos registros e menos suposições.

O CLI responde a essa pergunta no nível do ecossistema: uma forma de compartilhar blocos entre projetos e equipes sem agrupá-los em pacotes npm nem enfrentar sistemas de compilação.

A extensão PHPStan responde a essa pergunta no nível do código: ela detecta acessos a campos incorretos, erros de digitação em esquemas e callbacks de hooks com problemas antes que cheguem à execução.

Essa é a direção geral da versão 7.2: menos suposições, menos repetição, mais visibilidade e agora segurança de tipos de verdade.

## Correções de bugs

- **Campo de classes**: nomes de classes personalizados digitados pelo usuário eram descartados silenciosamente ao perder o foco, porque o validador aceitava apenas classes da lista predefinida de Tailwind/configurações. Agora, aceita qualquer string não vazia.
- **Campo de atributos**: a remoção de um par de atributos deixava entradas `null` nos dados salvos. Substituímos lodash `unset()` (que define elementos de arrays como nulos) por `splice()` (que os remove).
- **Minificador de CSS**: o minificador de TailwindPHP removia espaços em branco ao redor de `+` dentro de `calc()` e `clamp()`, gerando CSS inválido, como `calc(1rem+0.5vw)`. A correção foi feita no projeto original em TailwindPHP v1.3.1 com uma varredura de caracteres que considera a profundidade e só remove espaços em branco ao redor de combinadores de seletores no nível de parênteses 0.
- **Prévia do inseridor de blocos**: `$isPreview` sempre era `false` na prévia do inseridor de blocos porque o hash da chave do cache de renderização não incluía o modo de renderização. Agora, as renderizações do editor e da prévia geram entradas de cache separadas.
- **Template aninhado de InnerBlocks**: o componente `<InnerBlocks template="..."/>` descartava o terceiro elemento (filhos) de tuplas de template como `['core/group', {}, [['core/paragraph']]]`, gerando blocos contêiner vazios. Agora, preserva os filhos aninhados.
