@brucesantos/design-space 0.5.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,215 @@ Versionamento semântico. **Patch** para correção sem mudança de contrato,
6
6
  Mudança estrutural — pasta obrigatória nova, schema de cenário alterado — exige
7
7
  comando explícito e revisável, nunca merge silencioso.
8
8
 
9
+ ## 0.8.0 (2026-09-28)
10
+
11
+ **Major (incompatível).** Chrome novo, modelo de organização novo e a UI do
12
+ produto dentro de um `<iframe>`. Ver
13
+ `docs/decisions/0012-chrome-unico-telas-como-rotas-e-iframe.md`.
14
+
15
+ > **Primeira publicação depois da 0.6.0.** A 0.7.0 nunca foi publicada no npm:
16
+ > quem está em `^0.6.0` recebe as mudanças da 0.7.0 (acima, na seção dela) e as
17
+ > desta versão de uma vez. Leia os dois guias de migração, na ordem 0.7 → 0.8.
18
+
19
+ ### Removido
20
+
21
+ - **Módulos e jornadas:** `Module`, `Flow`, `FlowStep`, `ProductDefinition.modules`,
22
+ `ModuleNode`, `Registry.tree`, `Registry.orphans`, `Registry.treeFor`,
23
+ `Registry.orphansFor`, `Registry.module` e `Registry.flow`. A validação não
24
+ exige mais prefixo de módulo no id nem avisa quando falta; passos e
25
+ ramificações de jornada deixam de ser validados.
26
+ - **Home e palco inline:** `Home`, `HomeProps`, `Stage`, `StageProps`. A raiz
27
+ abre o primeiro item. `StageEmpty` continua exportado.
28
+ - **Rótulos:** os grupos `controls`, `inspector` e `home` e as chaves de fluxo e
29
+ de módulo em `sidebar` e `topbar` (`flowsTab`, `withoutModule`, `homeTitle`,
30
+ `toggleNav`, `panel`, `cleanReviewTitle`, `copyPrompt` de cenário…). Override
31
+ em `theme.labels` que declare esses grupos passa a ser erro de tipo.
32
+ - `buildHomeUrl`, `buildCleanReviewUrl`, `nextItemId` (eram exports internos do
33
+ shell, usados só em teste).
34
+
35
+ ### Adicionado
36
+
37
+ - **Telas e variações.** Uma tela é uma rota; as variações são os cenários cuja
38
+ `route` casa com o `path` (mesmo casamento e especificidade do roteador). Rota
39
+ sem cenário é tela com variação implícita "Padrão". `RouteDefinition.name` e
40
+ `RouteDefinition.description`. Nome da tela: `name` ?? título do primeiro
41
+ cenário ?? `path`.
42
+ - **Registry:** `screens`, `screen`, `screenForPath`, `screenOf`, `screensFor`
43
+ (com handoff), `searchScreens`, `searchComponents` (nome, descrição, grupo, id
44
+ e `source`, sem acento nem caixa), `componentsOfScreen`, `usagesOf`. Tipo
45
+ `ScreenNode`. `normalizeSearch` exportado.
46
+ - **`Scenario.components`**: ids de `ComponentPreview` usados na tela. Alimenta
47
+ "Componentes usados", o "Usado em" do componente e o "Copiar para o PR". Id
48
+ não registrado gera aviso.
49
+ - **`ComponentPreview.source`**: origem no sistema real, texto livre.
50
+ - **Chrome novo, preto e branco**, claro e escuro, sem cor de cliente e sem
51
+ logo. Seleção por tom (a cor do texto a 10%), grupos e abas em cápsula,
52
+ controles de 36px.
53
+ - Barra superior em três partes: o nome do produto e a versão do motor, com
54
+ link para o pacote; no centro, viewport (Celular 375, Tablet 768, Desktop
55
+ 1280, Ajustar), girar (só celular e tablet), zoom de 25% a 150% e revisão
56
+ limpa (`Shift` + `C`); à direita, copiar link, tema e o indicador de
57
+ diagnóstico. Em 100%, um viewport mais largo que a área encolhe até caber.
58
+ - Lateral esquerda: busca (`Cmd`/`Ctrl` + `K`) e as abas **Telas |
59
+ Componentes**, sempre visíveis; componentes agrupados por `group`, com
60
+ grupos recolhíveis.
61
+ - Lateral direita, sempre aberta com o chrome: filtro (`Cmd`/`Ctrl` + `F`)
62
+ e as abas **Variações | Informações**, com o botão **Copiar para o PR**.
63
+ - As duas laterais são redimensionáveis, e a largura é lembrada no navegador.
64
+ - **Quadro (`<iframe>`)**: a UI do produto roda na mesma origem e no mesmo
65
+ bundle, com `ds-frame=1`. A largura do viewport é a largura real da janela do
66
+ produto. Protocolo por `postMessage` validando origem e janela nos dois lados.
67
+ Exports `FRAME_PARAM` e `FRAME_ATTRIBUTE`; em `/testing`, `FRAME_SELECTOR`.
68
+ - **Estado na URL:** `zoom`, `rotate`, `tab` (aba do painel). `appearance` aceita
69
+ `dark` e `light`; sem ele, o tema segue a última escolha e, na falta dela, o
70
+ sistema. `ControlsState` ganha `zoom`, `rotated` e `panelTab`; tipo
71
+ `PanelTab`. `ZOOM_MIN`, `ZOOM_MAX`, `ZOOM_DEFAULT` e `clampZoom`.
72
+ - `useDesignSpaceState(registry, { frame })`; o retorno ganha `openScreen` e
73
+ `go`, e `openComponent` aceita `{ replace }`.
74
+ - **Validação de rotas:** `path` duplicado, `path` sem `/` inicial e `screen`
75
+ ausente são erro; `modules` ainda declarado vira aviso.
76
+
77
+ ### Alterado
78
+
79
+ - **`VIEWPORTS`**: `mobile` 375×812, `tablet` 768×1024, `desktop` 1280×800.
80
+ `custom` continua, só por URL (`viewport=custom&w=…`).
81
+ - **`ControlsState.chromeTheme`** fica `undefined` quando a URL não informa, em
82
+ vez de `dark`.
83
+ - **`scenariosForRoute`** devolve as variações da tela que renderiza o endereço,
84
+ pelo casamento de rota, e não mais cenários com o mesmo texto de caminho.
85
+ - **`validateScenario`**: id é minúsculo, kebab-case com pontos opcionais; não
86
+ precisa de prefixo.
87
+ - **`ProductDefinition.tagline`** continua no tipo, mas o chrome não o exibe.
88
+ - **CSS:** todos os seletores começam em `.ds-`; `.ds-root` agora define fundo,
89
+ fonte e cor e cobre a janela, porque o palco não é mais descendente dele. Os
90
+ tokens `--ds-*` foram todos renomeados para a paleta preto e branco.
91
+
92
+ ### Migração
93
+
94
+ 1. **Remova `modules`** da `ProductDefinition` (e os `flows` dentro dele). O
95
+ TypeScript aponta onde; se sobrar em JavaScript, o diagnóstico avisa.
96
+ 2. **Dê `name` às rotas** — é o nome da tela na lista. Opcionalmente, uma
97
+ `description`. Sem `name`, a tela usa o título do primeiro cenário da rota.
98
+ 3. **Ids de cenário continuam válidos.** O prefixo de módulo deixa de ter
99
+ significado, mas não precisa mudar: links antigos continuam abrindo.
100
+ 4. **Opcional:** liste em `components` de cada cenário os ids de componente que
101
+ a tela usa, e preencha `source` em cada `ComponentPreview`. É o que alimenta
102
+ "Componentes usados" e o "Copiar para o PR".
103
+ 5. **Troque container queries por media queries** onde elas existiam só porque
104
+ o palco não era uma janela. Dentro do quadro, `md:`/`lg:` respondem à largura
105
+ do viewport escolhido.
106
+ 6. **Testes de ponta a ponta:** a UI do produto está num iframe. Use
107
+ `page.frameLocator(FRAME_SELECTOR)` (de `@brucesantos/design-space/testing`)
108
+ para a UI e `page` para o chrome. Links do produto dentro do quadro navegam
109
+ sem recarregar e atualizam a URL do chrome.
110
+ 7. **Rótulos:** se `theme.labels` sobrescrevia `controls`, `inspector` ou `home`,
111
+ mova para `panel`, `info`, `diagnostics` e `shell`; o TypeScript aponta cada
112
+ chave. `EN_US_LABELS` já traz o dicionário novo completo.
113
+ 8. **CSS global do produto:** nada a fazer. O chrome define os próprios estilos
114
+ e ignora preflight e `body { … }` do produto. Se o produto dependia de algo
115
+ do chrome herdado no palco, isso acabou — o que é o objetivo.
116
+ 9. Links antigos com `module`, `flow`, `view`, `showPorted` ou parâmetros de
117
+ acessibilidade abrem sem erro: os parâmetros são ignorados.
118
+
119
+ ## 0.7.0 (2026-09-28) — não publicada
120
+
121
+ **Major (incompatível).** O motor deixa de impor acessibilidade e ciclo de vida
122
+ de cenário. Todo cenário registrado é simplesmente exibido. Ver
123
+ `docs/decisions/0011-revoga-a11y-e-ciclo-de-vida.md`.
124
+
125
+ ### Removido
126
+
127
+ - **Ciclo de vida do cenário:** `Scenario.status`, `Scenario.approvedAt`,
128
+ `ScenarioStatus`, `SCENARIO_STATUSES`, `ScenarioView`, `ControlsState.view` e
129
+ `showPorted`, a visão de referências portadas, a legenda e as contagens por
130
+ status na Home, na navegação e no Diagnóstico, os marcadores de status e os
131
+ parâmetros de URL `view` e `showPorted`. `Registry.byStatus` e
132
+ `Registry.coverage` saíram; `ScenarioQueryOptions` agora só tem `handoff`.
133
+ `useDesignSpaceState` não devolve mais `setScenarioView`. `Home` e `Sidebar`
134
+ perderam `view`, `onViewChange` e `showPorted`; `buildHomeUrl` perdeu o
135
+ parâmetro de visão.
136
+ - **Acessibilidade:** `Scenario.a11y`, `A11yContract`, `KeyboardCoverage`,
137
+ `ContrastTarget`, `ContrastPair`, `ProductTheme.contrastPairs`,
138
+ `ScenarioContext.a11y`, `ComponentPreviewProps.a11y`, todo `src/a11y/`
139
+ (`contrastRatio`, `checkContrastPair(s)`, `assertContrastPairs`,
140
+ `CONTRAST_THRESHOLDS`, `parseColor`, `flatten`, `relativeLuminance`,
141
+ `readCssVariable`, `computeRole`, `describeElement`, `shortSelector`,
142
+ `tabbableElements`, `useKeyboardMode` e tipos), `TabOrderOverlay`, o modo
143
+ teclado (atalho `Shift` + `K`), redução de movimento e ampliação de texto
144
+ (`TEXT_SCALES`, `keyboardMode`, `reducedMotion`, `textScale` e os parâmetros
145
+ `kb`, `motion`, `scale`), a aba Acessibilidade do Inspector.
146
+ `StageProps` ficou só com `viewport` e `children`.
147
+ - **Rótulos:** grupos `status`, `statusMeaning` e `keyboard`; exports
148
+ `STATUS_LABELS`, `STATUS_MEANING` e `KEYBOARD_LABELS`; as chaves de
149
+ referências portadas, aprovação, contraste e modo teclado em `sidebar`,
150
+ `controls`, `inspector` e `home`. Override em `theme.labels` que declare esses
151
+ grupos passa a ser erro de tipo.
152
+ - **`/testing`:** `scenariosUnderTest`, `keyboardScenarios` e a reexportação das
153
+ funções de contraste. Continuam `testOrigin`, `urlFor`, `pathFor`,
154
+ `scenarioUrl`, `assertValidProduct`, `validateProduct`, `hasErrors` e
155
+ `formatIssues`.
156
+
157
+ ### Alterado
158
+
159
+ - **`persona` é opcional em `Scenario`.** Cenário sem persona tem permissões
160
+ vazias, a menos que declare `permissions`. A validação só reclama de persona
161
+ inexistente quando ela é informada, e `scenarioUrl()` omite `persona` da URL
162
+ quando o cenário não declara uma.
163
+ - **Produto só de componentes é válido.** `routes` vazio só é erro quando há
164
+ cenários. Sem cenários e com `components`, a Home abre no catálogo de
165
+ componentes agrupado por `group`, e a navegação abre direto na lista de
166
+ componentes, sem aba de fluxos vazia.
167
+ - A Home sem cenário nem componente mostra um único estado vazio
168
+ (`home.noScenarios`); a navegação usa `sidebar.emptyScenarios`. Novo rótulo
169
+ `home.componentsLead`.
170
+
171
+ ### Migração
172
+
173
+ 1. Apague `a11y`, `status` e `approvedAt` de todos os cenários e
174
+ `theme.contrastPairs` da definição do produto.
175
+ 2. `persona` agora é opcional: mantenha onde ela decide permissões, remova onde
176
+ não acrescenta nada.
177
+ 3. Remova de `theme.labels` os grupos `status`, `statusMeaning` e `keyboard` e as
178
+ chaves listadas acima; o TypeScript aponta cada uma.
179
+ 4. Se os testes do produto usavam `scenariosUnderTest`, `keyboardScenarios` ou
180
+ as funções de contraste de `/testing`, troque por `product.scenarios` (ou um
181
+ filtro do próprio produto) e apague os testes de contraste e axe que
182
+ dependiam delas.
183
+ 5. Links antigos com `view=ported`, `showPorted=1`, `kb=1`, `motion=1` ou
184
+ `scale=…` continuam abrindo: os parâmetros são ignorados.
185
+
186
+ ## 0.6.0 (2026-08-13)
187
+
188
+ ### Adicionado
189
+
190
+ - **Escopo explícito de handoff por URL.** `HandoffScope` traz allowlists neutras
191
+ de cenários, padrões de rota e componentes. O formato legível usa `handoff=1`
192
+ com parâmetros repetíveis `allowScenario`, `allowRoute` e `allowComponent`.
193
+ - Home, árvore, busca, flows, referências portadas e catálogo de componentes
194
+ respeitam o recorte. Navegação interna e links de Home/revisão limpa o
195
+ preservam; tentativas fora do escopo recebem mensagem clara sem montar a tela
196
+ solicitada.
197
+ - Helpers públicos `applyHandoffScope`, `parseHandoffScope`,
198
+ `normalizeHandoffScope`, `handoffAllowsScenario`, `handoffAllowsPath` e
199
+ `handoffAllowsComponent` permitem construir e verificar o mesmo contrato fora
200
+ do shell. `scenarioUrl()` e `componentUrl()` aceitam o recorte em
201
+ `overrides.handoff`.
202
+
203
+ ### Alterado
204
+
205
+ - O Inspector agrupa visual e semanticamente dados da tarefa e contexto herdado
206
+ do produto/persona. A aba Acessibilidade distingue contrato da tarefa,
207
+ inspeção ao vivo da tela e verificações gerais do produto; Diagnóstico declara
208
+ que continua avaliando o catálogo inteiro.
209
+ - Cenário `approved` sem `approvedAt` aparece como **Aprovado — registro
210
+ pendente**, com alerta no painel e warning equivalente no validador. O status
211
+ e o marcador só recebem tratamento completo de aprovação quando existe uma URL
212
+ de commit registrada.
213
+
214
+ O handoff é bloqueio de foco/UX, não controle de acesso. Preview que exige
215
+ isolamento real precisa de build separado ou autenticação/autorização no produto.
216
+ Não há mudança obrigatória no schema de `Scenario` nem nos catálogos existentes.
217
+
9
218
  ## 0.5.1 (2026-08-12)
10
219
 
11
220
  ### Adicionado
package/README.md CHANGED
@@ -1,9 +1,14 @@
1
1
  # @brucesantos/design-space
2
2
 
3
- Motor neutro do Bananas Design Space. Fornece o ambiente — navegação por cenário,
4
- deep links, controles de persona/dados/viewport/rede, painel de contexto e
5
- ferramentas de acessibilidade — sem impor nenhum componente visual, token ou
6
- identidade ao produto.
3
+ Motor neutro do Bananas Design Space. Fornece o ambiente de revisão — telas e
4
+ componentes à esquerda, variações e informações à direita, deep links, controles
5
+ de persona/rede/viewport/zoom e o texto pronto para o PR — sem impor nenhum
6
+ componente visual, token ou identidade ao produto.
7
+
8
+ O chrome é o mesmo para todos os produtos: preto e branco, claro e escuro, sem
9
+ cor de cliente. A UI do produto roda num `<iframe>` da mesma origem e do mesmo
10
+ bundle, com a largura do viewport escolhido: CSS isolado nos dois sentidos, e
11
+ media queries respondendo como em produção.
7
12
 
8
13
  ```bash
9
14
  pnpm add @brucesantos/design-space
@@ -23,11 +28,33 @@ export function App() {
23
28
  }
24
29
  ```
25
30
 
31
+ ## Telas e variações
32
+
33
+ **Uma tela é uma rota.** As **variações** de uma tela são os cenários cuja
34
+ `route` casa com o `path` dela — pelo mesmo casamento do roteador, então
35
+ `/requests/REQ-2043` é variação de `/requests/:id`, e `/requests/new` fica com a
36
+ rota literal. A ordem das telas é a de `routes`; a das variações, a de
37
+ `scenarios`. Rota sem cenário também é tela, aberta numa variação "Padrão".
38
+
39
+ ```ts
40
+ routes: [
41
+ { path: "/requests", screen: RequestList, name: "Fila de solicitações" },
42
+ {
43
+ path: "/requests/:id",
44
+ screen: RequestDetail,
45
+ name: "Detalhe da solicitação",
46
+ description: "Análise e decisão de uma solicitação.",
47
+ },
48
+ ],
49
+ ```
50
+
51
+ Sem `name`, a tela usa o título do primeiro cenário da rota e, na falta dele, o
52
+ `path`. Não existe módulo nem jornada (decisão 0012).
53
+
26
54
  ## O contrato de cenário
27
55
 
28
56
  Um cenário combina intenção, persona, permissões, pré-condições, dados, ações,
29
- regras e resultado esperado. É a unidade central: não é uma tela com dados
30
- diferentes.
57
+ regras e resultado esperado. O `title` é o nome da variação na lista.
31
58
 
32
59
  ```ts
33
60
  import type { Scenario } from "@brucesantos/design-space";
@@ -35,55 +62,54 @@ import type { Scenario } from "@brucesantos/design-space";
35
62
  export const approveBlocked: Scenario = {
36
63
  id: "requests.approve-blocked",
37
64
  title: "Aprovação bloqueada por falta de documento",
65
+ intent: "Verificar se a regra fica legível na tela.",
38
66
  route: "/requests/REQ-2043",
39
67
  persona: "approver",
40
68
  permissions: ["requests.read", "requests.approve"],
41
69
  fixture: "request-without-document",
42
70
  rules: ["approval-needs-document"],
43
- a11y: {
44
- keyboard: "full",
45
- contrast: "AA",
46
- announces: ["request.status", "approval.result"],
47
- },
48
- status: "approved",
71
+ expected: ["O motivo do bloqueio aparece junto da ação indisponível."],
72
+ components: ["actions.primary-button", "feedback.notice"],
49
73
  };
50
74
  ```
51
75
 
52
76
  O vocabulário do exemplo é genérico de propósito: o domínio é do produto, nunca do
53
77
  motor.
54
78
 
55
- `a11y` é obrigatório. Acessibilidade é campo do contrato, não auditoria de fim de
56
- projeto: um cenário de ação bloqueada em que o bloqueio não é anunciado para leitor
57
- de tela está incompleto, não está pronto para aprovação.
58
-
59
- ### Ciclo de vida
60
-
61
- O estado diz o que o cenário representa; importar uma tela existente não a torna
62
- proposta nem compromisso de implementação.
63
-
64
- | Valor | Rótulo padrão | Significado |
65
- | --- | --- | --- |
66
- | `ported` | Portado — não validado | Veio do sistema existente, mas não foi validado e não representa compromisso de implementação. |
67
- | `proposed` | Proposta | Exploração ainda não aprovada. |
68
- | `in-review` | Em revisão | Aberto para validação de design, negócio ou cliente. |
69
- | `approved` | Aprovado | Referência autorizada, registrada por URL de commit. |
70
- | `in-implementation` | Em implementação | Ligado a um trabalho ativo de engenharia. |
71
- | `implemented` | Implementado | Disponível no produto real e validado. |
72
- | `superseded` | Superado | Mantido para histórico ou substituído por outra decisão. |
73
-
74
- `scenariosUnderTest()` inclui por padrão apenas `approved`, `in-implementation` e
75
- `implemented`. Cenários `ported` ficam fora até serem promovidos, mas podem ser
76
- selecionados explicitamente pelo segundo argumento.
77
-
78
- Na interface, `ported` vive numa coleção separada. **Trabalho ativo** mostra apenas
79
- cenários não portados; **Referências portadas** mostra apenas portados. A entrada
80
- textual “Ver N referências portadas” troca de coleção e grava `view=ported` na URL.
81
- Busca, home, módulos e contagens seguem a visão atual, sem renderizar módulos
82
- vazios. Um deep link direto para um portado infere a visão de referências mesmo
83
- sem o parâmetro. Links 0.4.0 com `showPorted=1` continuam sendo lidos e são
84
- normalizados para a nova visão. O diagnóstico sempre avalia o catálogo completo.
85
- A home também apresenta uma legenda estável com a cor, o rótulo e o significado
86
- de cada status; os chips de contagem continuam mostrando apenas a visão atual.
79
+ - `id` é qualquer id estável, minúsculo, em kebab-case com pontos opcionais.
80
+ Precisa ser único; não precisa de prefixo.
81
+ - `persona` é opcional. Cenário sem persona tem permissões vazias, a menos que
82
+ declare `permissions`.
83
+ - `components` lista os ids de `ComponentPreview` usados na tela. Alimenta
84
+ "Componentes usados", o "Usado em" de cada componente e o "Copiar para o PR".
85
+
86
+ ## O chrome
87
+
88
+ | Região | Conteúdo |
89
+ | --- | --- |
90
+ | Barra superior | Nome do produto; viewport (Celular 375, Tablet 768, Desktop 1280, Ajustar), girar, zoom 25–150%, copiar link, revisão limpa, tema, painel e — quando a validação tem algo a dizer — o indicador de diagnóstico. |
91
+ | Esquerda | **Telas** e **Componentes**, com contagem e busca sem acento nem caixa (nome, descrição, grupo, id e `source`). Componentes agrupados por `group`. Aba vazia some. Redimensionável. |
92
+ | Centro | O quadro do produto no tamanho do viewport, com zoom só de visualização. |
93
+ | Direita | **Variações** (cenários da tela ou fixtures do componente, mais persona e rede) e **Informações** (rota, intenção, pré-condições, ações, comportamento esperado, regras, componentes usados e **Copiar para o PR**). Redimensionável. |
94
+
95
+ Sem Home: a raiz abre a primeira tela na primeira variação ou, sem telas, o
96
+ primeiro componente. O tema segue o sistema, e a troca é lembrada.
97
+
98
+ ### Copiar para o PR
99
+
100
+ Gera markdown com o nome da tela, um link absoluto por variação (com o link do
101
+ deployment e o commit quando o produto informa), a tabela componente → origem e
102
+ o comportamento esperado de cada variação.
103
+
104
+ ### O quadro
105
+
106
+ O chrome renderiza `<iframe data-ds-frame>` apontando para o mesmo endereço com
107
+ `ds-frame=1`. Nesse modo, `<DesignSpace>` renderiza **só** o wrapper do produto e
108
+ a tela ou o preview. Trocar variação, persona ou rede vai por `postMessage`, sem
109
+ recarregar; trocar de tela ou de componente troca o endereço do quadro sem criar
110
+ entrada no histórico. Navegação feita pela UI do produto (`context.navigate`,
111
+ `openScenario` ou um link comum) volta para a URL do chrome. Os dois lados só
112
+ aceitam mensagem da mesma origem e da janela esperada.
87
113
 
88
114
  ## A URL é o estado
89
115
 
@@ -94,30 +120,78 @@ rede declarados no cenário.
94
120
  | Parâmetro | Efeito |
95
121
  | --- | --- |
96
122
  | `scenario` | Cenário ativo. Define os padrões dos demais. |
97
- | `view=ported` | Abre a coleção de referências portadas. Omitido significa trabalho ativo. |
98
123
  | `component` | Referência ativa no catálogo visual do produto. |
99
124
  | `persona` | Troca o papel e as permissões. |
100
125
  | `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. |
101
- | `showPorted=1` | Compatibilidade de leitura com links 0.4.0; equivale a `view=ported`. |
102
126
  | `network` | `success`, `loading`, `empty`, `error`, `slow`. |
103
- | `viewport` | `fit`, `mobile`, `tablet`, `desktop`, `custom`. |
127
+ | `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
104
128
  | `w` | Largura, quando `viewport=custom`. |
129
+ | `rotate=1` | Troca largura e altura do viewport. |
130
+ | `zoom` | Zoom da visualização, 25–150. Omitido em 100. |
105
131
  | `theme`, `locale`, `source` | Variações declaradas pelo produto. |
106
- | `appearance` | Aparência do chrome: omitido para dark, `light` para modo claro. |
132
+ | `appearance` | Tema do chrome, `light` ou `dark`. Omitido: última escolha ou o sistema. |
107
133
  | `chrome=0` | Revisão limpa: oculta o chrome do ambiente. |
108
- | `kb=1` | Modo teclado, com ordem de tabulação evidenciada. |
109
- | `motion=1` | Movimento reduzido no palco. |
110
- | `scale` | Ampliação de texto: `1`, `1.25`, `1.5`, `2`. |
111
- | `panel=0` | Oculta o painel de contexto. |
134
+ | `panel=0` | Oculta o painel direito. |
135
+ | `tab=info` | Abre o painel direito em Informações. |
136
+ | `handoff=1` | Ativa um recorte explícito de revisão/handoff. |
137
+ | `allowScenario` | Cenário permitido; pode ser repetido e autoriza também a rota do cenário. |
138
+ | `allowRoute` | Padrão de rota permitido, como `/requests/:id`; pode ser repetido. |
139
+ | `allowComponent` | Componente permitido; pode ser repetido. |
140
+
141
+ ## Handoff focado por URL
142
+
143
+ O handoff é uma allowlist transportada junto dos demais controles. Ela filtra
144
+ telas, variações, busca e componentes. A raiz abre o primeiro item permitido;
145
+ uma tentativa de abrir cenário, rota ou componente fora da lista mostra um
146
+ bloqueio claro no quadro, sem montar a tela solicitada. Links internos da UI do
147
+ produto carregam o recorte.
148
+
149
+ ```ts
150
+ import {
151
+ scenarioUrl,
152
+ type HandoffScope,
153
+ } from "@brucesantos/design-space";
154
+
155
+ const handoff = {
156
+ scenarios: ["requests.approve-blocked", "requests.approve-allowed"],
157
+ routes: ["/help/:topic"],
158
+ components: ["actions.primary-button"],
159
+ } satisfies HandoffScope;
160
+
161
+ const url = scenarioUrl(approveBlocked, {
162
+ origin: "https://review.example.test",
163
+ overrides: { handoff },
164
+ });
165
+ ```
166
+
167
+ O endereço resultante usa parâmetros repetíveis e legíveis:
168
+
169
+ ```text
170
+ ?scenario=requests.approve-blocked&persona=approver&fixture=request-without-document&handoff=1&allowScenario=requests.approve-allowed&allowScenario=requests.approve-blocked&allowRoute=%2Fhelp%2F%3Atopic&allowComponent=actions.primary-button
171
+ ```
172
+
173
+ As listas são uma união: cenários tornam suas próprias rotas acessíveis, rotas
174
+ explícitas cobrem páginas sem cenário e componentes precisam ser listados
175
+ separadamente. `applyHandoffScope()` e `parseHandoffScope()` constroem ou leem o
176
+ mesmo contrato em URLs próprias.
177
+
178
+ Este recorte é um bloqueio de foco/UX, **não segurança**. O bundle e o catálogo
179
+ continuam no navegador. Preview público que precisa ocultar de fato o restante do
180
+ produto exige build separado para o recorte ou autenticação/autorização no
181
+ produto que publica o preview.
182
+
183
+ O indicador de diagnóstico continua deliberadamente geral: avalia o catálogo
184
+ inteiro, inclusive fora do handoff.
112
185
 
113
186
  ## API
114
187
 
115
188
  ### Shell
116
189
 
117
- - `DesignSpace` — o ambiente completo.
118
- - `Home` — mapa de situações, usado na raiz.
119
- - `Stage`, `StageEmpty`, `TabOrderOverlay` — partes do palco, expostas para casos
120
- fora do padrão.
190
+ - `DesignSpace` — o ambiente completo: chrome no documento de cima, UI do
191
+ produto no quadro.
192
+ - `StageEmpty` — estado vazio neutro, para `notFound` e casos fora do padrão.
193
+ - `FRAME_PARAM`, `FRAME_ATTRIBUTE` — o parâmetro do modo quadro e o atributo do
194
+ `<iframe>`.
121
195
 
122
196
  ### Rótulos do chrome
123
197
 
@@ -127,9 +201,9 @@ não for declarado fica no padrão.
127
201
  ```ts
128
202
  theme: {
129
203
  labels: {
130
- status: { approved: "Approved", "in-review": "In review" },
204
+ network: { success: "Success", error: "Error" },
131
205
  topbar: { copyLink: "Copy link" },
132
- home: { lead: (total) => `${total} scenarios, each one a link.` },
206
+ info: { copyForPr: "Copy for PR" },
133
207
  },
134
208
  }
135
209
  ```
@@ -140,7 +214,7 @@ theme: {
140
214
  - `useLabels()` — os rótulos resolvidos, dentro do chrome.
141
215
  - `Labels`, `LabelsOverride` — os tipos.
142
216
 
143
- Rótulo de **produto** continua vindo do produto: nome de módulo, título de cenário,
217
+ Rótulo de **produto** continua vindo do produto: nome de tela, título de cenário,
144
218
  nome de persona, rótulo de fixture.
145
219
 
146
220
  Para usar o chrome integralmente em en-US:
@@ -159,27 +233,34 @@ const product = {
159
233
 
160
234
  ### Aparência do chrome
161
235
 
162
- O seletor na topbar alterna entre dark e light sem alterar tokens ou tema da UI
163
- do produto. A escolha é serializada como `?appearance=light`, então links copiados
164
- e a revisão limpa preservam a aparência escolhida.
236
+ Preto e branco, igual em todo produto. O botão de tema alterna claro e escuro sem
237
+ tocar na UI do produto; a escolha vai para `?appearance=` e fica lembrada no
238
+ navegador. Sem escolha, vale o `prefers-color-scheme` do sistema. Não existe
239
+ tema, cor ou logo por produto.
165
240
 
166
241
  ### Registry e validação
167
242
 
168
- - `createRegistry(product)` — índice consultável: busca por vocabulário de
169
- negócio, árvore de módulos, cobertura por status.
170
- - `activeScenarios()`, `treeFor()`, `orphansFor()`, `search()` e `coverage()` —
171
- consultam trabalho ativo por padrão e aceitam `{ view: "ported" }` para a
172
- biblioteca de referências. `{ includePorted: true }` permanece disponível para
173
- diagnóstico e consultas do catálogo completo. `tree` e `issues` continuam
174
- completos.
243
+ - `createRegistry(product)` — índice consultável.
244
+ - `screens`, `screen(id)`, `screenForPath(path)`, `screenOf(scenario)` — telas
245
+ (`ScreenNode`) e suas variações.
246
+ - `screensFor({ handoff })`, `activeScenarios()`, `search()`,
247
+ `searchScreens()`, `searchComponents()`, `componentsFor(handoff)` — aplicam o
248
+ recorte; a busca não diferencia acento nem caixa (`normalizeSearch`).
249
+ - `componentsOfScreen(screen)`, `usagesOf(componentId)` — componentes de uma
250
+ tela e telas de um componente, a partir de `Scenario.components`.
175
251
  - `validateProduct(product)` / `validateScenario(scenario)` — validação em runtime
176
- do contrato. Pega fixture, persona, regra ou rota inexistente, que o TypeScript
177
- não alcança.
252
+ do contrato. Pega fixture, persona, regra ou rota inexistente, rota duplicada,
253
+ id duplicado e componente citado sem registro — o que o TypeScript não
254
+ alcança. `routes` vazio só é erro quando há cenários, então um produto que é
255
+ só catálogo de componentes é válido.
178
256
 
179
257
  ### Catálogo de componentes
180
258
 
181
- O catálogo é opcional. O motor fornece navegação, busca e deep link; cada preview
182
- continua sendo UI do produto:
259
+ O motor fornece navegação, busca e deep link; cada preview continua sendo UI do
260
+ produto. Um produto pode ser só catálogo: com `scenarios`, `fixtures` e `routes`
261
+ vazios, a aba Telas some e a raiz abre o primeiro componente. As **variações** de
262
+ um componente são as `fixtures` dele; `source` diz de onde ele vem no sistema
263
+ real.
183
264
 
184
265
  ```tsx
185
266
  type ButtonData = {
@@ -193,7 +274,6 @@ function PrimaryButtonPreview({
193
274
  viewport,
194
275
  themeMode,
195
276
  locale,
196
- a11y,
197
277
  }: ComponentPreviewProps<ButtonData>) {
198
278
  return (
199
279
  <button disabled={data?.disabled} data-viewport={viewport.id}>
@@ -210,6 +290,7 @@ const product: ProductDefinition = {
210
290
  name: "Botão primário",
211
291
  group: "Ações",
212
292
  description: "Ação principal da página",
293
+ source: "components/button.ex → button/1",
213
294
  preview: PrimaryButtonPreview,
214
295
  defaultFixture: "default",
215
296
  fixtures: [
@@ -238,10 +319,9 @@ const product: ProductDefinition = {
238
319
  Abrir o exemplo produz
239
320
  `?component=actions.primary-button&fixture=default`; trocar os dados para o
240
321
  estado desabilitado produz
241
- `?component=actions.primary-button&fixture=disabled`. O seletor só aparece quando
242
- o componente declara fixtures. Se a URL pedir uma fixture inexistente, o preview
243
- usa `defaultFixture` (ou a primeira fixture) e o painel nomeia o fallback; a URL
244
- inválida não é descartada silenciosamente.
322
+ `?component=actions.primary-button&fixture=disabled`. Se a URL pedir uma fixture
323
+ inexistente, o preview usa `defaultFixture` (ou a primeira fixture) e o painel
324
+ nomeia o fallback; a URL inválida não é descartada silenciosamente.
245
325
 
246
326
  `ComponentPreview`, `ComponentPreviewFixture` e `ComponentPreviewProps` são os
247
327
  tipos públicos. Um preview 0.3.0 sem props continua compatível:
@@ -276,7 +356,7 @@ omite branch e commit.
276
356
  consome.
277
357
  - `scenarioUrl(scenario, options)` — URL absoluta reproduzível.
278
358
  - `componentUrl(component, options)` — URL absoluta do componente com sua fixture.
279
- - `commitUrl(scenario, { template })` — URL imutável para registrar aprovação. O
359
+ - `commitUrl(scenario, { template })` — URL imutável do cenário num commit. O
280
360
  template é do produto, com `{commit}` ou `{shortCommit}`.
281
361
 
282
362
  ### Dados
@@ -285,15 +365,6 @@ omite branch e commit.
285
365
  - `createHttpAdapter(options)` — adapter REST/GraphQL com fallback para fixture.
286
366
  - `useScenarioData(...)` — resolução do cenário ativo pelo adapter selecionado.
287
367
 
288
- ### Acessibilidade
289
-
290
- - `contrastRatio(fg, bg)`, `checkContrastPairs(pairs)`, `assertContrastPairs(pairs)`
291
- — razão de contraste do WCAG 2.x, com composição de alfa sobre o fundo.
292
- `assertContrastPairs` falha o build a partir de um teste do produto.
293
- - `describeElement(el)` — papel, nome acessível, origem do nome e estados.
294
- - `tabbableElements(root)` — ordem de tabulação real.
295
- - `useKeyboardMode(enabled, ref)` — foco observado e ordem de tabulação medida.
296
-
297
368
  ### Testes
298
369
 
299
370
  `@brucesantos/design-space/testing` — entrypoint separado, fora do bundle do
@@ -304,31 +375,41 @@ preview.
304
375
  - `testOrigin(fallback)` — lê `PREVIEW_URL` quando existe um ambiente publicado
305
376
  para testar; sem ela, o Playwright roda contra o dev server local.
306
377
  - `assertValidProduct(product)` — falha o teste quando o contrato tem erro.
307
- - `scenariosUnderTest(product)`, `keyboardScenarios(product)` — recortes para
308
- parametrizar jornadas.
378
+ - `FRAME_SELECTOR` — o seletor do quadro. A UI do produto está num iframe:
379
+
380
+ ```ts
381
+ await page.goto(pathFor(scenario));
382
+ const app = page.frameLocator(FRAME_SELECTOR);
383
+ await expect(app.getByRole("heading", { name: "Fila" })).toBeVisible();
384
+ await expect(page).toHaveURL(/scenario=/); // o chrome fica em `page`
385
+ ```
309
386
 
310
387
  ## Atalhos
311
388
 
312
389
  | Atalho | Efeito |
313
390
  | --- | --- |
314
- | `Command/Ctrl` + `K` ou `F` | Foco na busca da lateral |
315
- | `↑` / `↓` | Percorrer resultados filtrados |
316
- | `Shift` + `K` | Modo teclado |
317
- | `Shift` + `P` | Painel de contexto |
391
+ | `Command/Ctrl` + `K` | Foco na busca da lateral |
392
+ | `Shift` + `C` | Revisão limpa: esconde e mostra o chrome |
393
+ | `Command/Ctrl` + `F` | Foco no filtro do painel direito |
394
+
395
+ Os três funcionam também com o foco dentro do quadro; `Shift` + `C`, fora de
396
+ campos de texto.
318
397
 
319
398
  ## Créditos
320
399
 
321
- Os ícones dos presets de viewport são derivados do
322
- [Lucide](https://lucide.dev/), disponibilizado sob licença MIT. Obrigado às
323
- pessoas mantenedoras e contribuidoras do projeto. Os SVGs necessários são
324
- incorporados ao motor, portanto não existe dependência de runtime do Lucide.
400
+ Os ícones do chrome seguem o traço do [Lucide](https://lucide.dev/),
401
+ disponibilizado sob licença MIT. Obrigado às pessoas mantenedoras e
402
+ contribuidoras do projeto. Os SVGs são incorporados ao motor, portanto não existe
403
+ dependência de runtime do Lucide.
325
404
 
326
405
  ## Fronteira
327
406
 
328
407
  O motor **não** contém e não deve conter: componente visual, token, tipografia,
329
408
  cor, ícone, persona de domínio, fixture, regra de negócio ou conteúdo de cliente.
330
409
  Isso é exclusivo de cada produto — e é o que permite que dois produtos sobre o
331
- mesmo motor continuem parecendo produtos distintos.
410
+ mesmo motor continuem parecendo produtos distintos. O chrome em preto e branco é
411
+ ferramenta, não identidade: a identidade do cliente fica inteira dentro do
412
+ quadro.
332
413
 
333
414
  Três coisas que também não pertencem ao motor, cada uma travada por teste:
334
415
  provedor de hospedagem, texto visível fixo em componente do chrome e nome de