---
sidebar_position: 3
title: "Como Adicionar uma Atividade"
---

Este guia descreve o passo a passo para criar uma nova atividade de letramento na plataforma.

## Visão geral do processo

```mermaid
flowchart TD
    A[Criar pasta da atividade] --> B[Escrever index.html]
    B --> C[Implementar activity.js com contratos postMessage]
    C --> D[Registrar em letramentoRegistry.js]
    D --> E[Testar localmente]
    E --> F[Validar progresso persistido]
```

## 1. Criar a pasta da atividade

Escolha a categoria adequada e crie a estrutura:

```text
app/src/atividades/letramento/<categoria>/<nome-atividade>/
  index.html
  activity.js
```

Se a categoria ainda não existir, crie a pasta e atualize o registry com o novo agrupamento.

## 2. Escrever o index.html

A atividade é um documento HTML completo e autossuficiente. Pode usar qualquer recurso web padrão. O único requisito é que inclua o `activity.js`:

```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8" />
  <title>Nome da Atividade</title>
</head>
<body>
  <!-- conteúdo da atividade -->
  <script src="./activity.js"></script>
</body>
</html>
```

## 3. Implementar o activity.js

O `activity.js` deve emitir os estados corretos via `postMessage`:

```javascript
// Sinaliza que a atividade começou
window.parent.postMessage({ type: 'started' }, '*');

// Sinaliza sucesso ao final
function concluir(score) {
  window.parent.postMessage({ type: 'success', score }, '*');
}

// Sinaliza falha
function falhar() {
  window.parent.postMessage({ type: 'failure' }, '*');
}
```

Estados obrigatórios: ao menos `started` e (`success` ou `failure`).

## 4. Registrar em letramentoRegistry.js

Adicione a nova atividade ao array de registros:

```javascript
// app/src/atividades/letramento/letramentoRegistry.js
{
  id: 'nome-atividade',
  categoria: 'nome-categoria',
  trilha: 1,           // posição dentro da categoria
  title: 'Nome da Atividade',
  src: '/atividades/letramento/categoria/nome-atividade/index.html',
}
```

Referência externa: https://martinfowler.com/eaaCatalog/registry.html

## 5. Validar localmente

```bash
cd app
pnpm run dev
```

Acesse a atividade na interface, verifique:

- A atividade carrega sem erros de console.
- Os estados `started`, `success` e `failure` chegam ao React (visível via DevTools → mensagens ou estado do contexto).
- O progresso é salvo no `localStorage` após `success`.
