# MarkPin

**Seu Markdown, local. Sua IA, sob controle.**

MarkPin é um editor Markdown local-first para anotações rápidas, documentos extensos e integração opcional com chats de IA. O produto combina uma aplicação web/PWA, uma janela flutuante baseada em Document Picture-in-Picture e a extensão **MarkPin Companion** para Chrome.

> Status: MVP funcional / beta técnico.

## O que já está implementado

### Web e PWA

- Biblioteca com múltiplas notas, fixadas, favoritas, arquivadas e lixeira.
- Pastas e tags com autocomplete, criação durante a digitação, busca em Web Worker e atalhos de teclado.
- Editor CodeMirror 6 com preview Markdown sanitizado.
- GitHub Flavored Markdown, links `[[entre notas]]` e callouts `:::note`.
- Layout editor, preview ou tela dividida.
- Modo foco, temas claro/escuro/sistema e interface responsiva com elementos ampliados para desktop, tablet e celular.
- Menu lateral expansível ou compacto em ícones, com preferência salva localmente.
- Salvamento automático com revisão SHA-256.
- Histórico local, snapshots, visualização e restauração.
- Armazenamento híbrido: OPFS quando disponível e fallback para IndexedDB.
- Solicitação opcional de armazenamento persistente.
- Importação de `.md` e backup/restauração JSON.
- Exportação de Markdown.
- Imagens incorporadas por arquivo local.
- Português e inglês com detecção pelo idioma do navegador; fallback `pt-BR`.
- PWA instalável e utilizável offline.
- Atualização controlada do Service Worker.

### Modo flutuante PiP

- Janela sempre visível quando Document Picture-in-Picture está disponível.
- Edição compacta com autosave.
- Alternância entre editor e preview.
- Busca e navegação entre notas com título e trecho inicial dentro da própria janela.
- Criação de notas e retorno rápido ao aplicativo principal.
- Fallback para janela popup em navegadores sem Document PiP.

### MarkPin Companion

- Código-fonte incluído no mesmo repositório em [`apps/extension`](apps/extension).
- Extensão Chrome Manifest V3 com painel lateral ampliado.
- Navegação expandida ou compacta em ícones, com preferência persistente.
- Temas claro, escuro e sistema; tamanhos normal, grande e extra grande.
- Endereço padrão configurável por `MARKPIN_DEFAULT_URL` e sobrescrevível no painel.
- Sincronização de cada conversa do ChatGPT em uma única nota, sem duplicações.
- Opção para incluir mensagens do usuário, da IA ou ambas.
- Captura de respostas, seleções, páginas, links, imagens e vídeos.
- Web Clipper com extração do conteúdo principal para Markdown.
- Caixa de entrada diária opcional.
- Sessões de pesquisa com fontes acumuladas automaticamente.
- Workspaces de abas salvos e restauráveis.
- Busca de notas pela barra de endereço usando `mp`.
- Receitas de captura padrão e personalizadas.
- Capturas para desenvolvedores: snippets, erros/logs, comandos e ADRs.
- Atalhos configuráveis em `chrome://extensions/shortcuts`.
- Notas relacionadas à página atual.
- Fluxo MarkPin → ChatGPT → ação estruturada revisável.
- Notificações opcionais para falhas e ações que exigem atenção.
- Fila local quando o MarkPin estiver fechado.
- Comunicação local extensão ↔ aplicação sem backend.
- Nenhum JavaScript remoto, `eval` ou script baixado em runtime.
- Link de instalação exibido pelo site quando `VITE_COMPANION_URL` estiver configurada.

### Segurança das notas

- Notas sensíveis ficam bloqueadas para ações de IA.
- A IA não pode excluir notas, limpar histórico ou alterar sensibilidade.
- Atualizações completas exigem `baseRevision` para detectar conflitos.
- Toda alteração relevante pode gerar snapshot anterior.
- Conteúdo Markdown passa por sanitização antes do preview.
- Nenhum backend, conta ou telemetria no MVP.

## Arquitetura

```text
MarkPin Web/PWA
├── React + TypeScript + Vite
├── CodeMirror 6
├── IndexedDB (metadados e fallback)
├── OPFS (conteúdo e histórico)
├── Web Worker (busca)
├── Document Picture-in-Picture
└── MarkPin Action Protocol

MarkPin Companion
├── Chrome Manifest V3
├── Service worker da extensão
├── Side panel
├── Adaptador ChatGPT
├── Adaptador genérico por seleção
└── Ponte local com o MarkPin Web
```

A aplicação web é a única dona das notas. A extensão armazena apenas configurações e ações pendentes.

## Requisitos

- Node.js `22.16.0` ou superior compatível com Vite 8.
- npm `10.9.0` ou superior.
- Chrome/Chromium recente para o melhor suporte ao PiP e à extensão.

## Instalação segura

O projeto bloqueia scripts de ciclo de vida de dependências por padrão através do `.npmrc`.

```bash
npm run install:safe
npm run security:scripts
npm audit --audit-level=high
```

> A instalação segura não executa scripts de dependências e não dispara auditoria automática. Isso evita travamentos por indisponibilidade do endpoint de auditoria. O CI executa a auditoria separadamente.

### Instalação travada

Confirme Node.js 22.12+ e npm 10.9+, remova uma instalação incompleta e tente novamente:

```bash
rm -rf node_modules
npm cache verify
npm run install:safe
```

Depois da instalação:

```bash
npm run dev
```

O comando `security:scripts` falha se alguma dependência declarar `preinstall`, `install` ou `postinstall`.

## Desenvolvimento

```bash
# aplicação web
npm run dev

# testes
npm run test

# validação TypeScript
npm run typecheck

# build completo
npm run build
```

A aplicação ficará disponível normalmente em `http://localhost:5173`.

## Testar a extensão localmente

```bash
npm run build:extension
```

1. Abra `chrome://extensions`.
2. Ative o **Modo do desenvolvedor**.
3. Clique em **Carregar sem compactação**.
4. Selecione `dist/extension`.
5. Abra o MarkPin uma vez para que a extensão registre o endereço local.
6. Abra o side panel e habilite a integração com ChatGPT.

## Gerar o ZIP da extensão

```bash
npm run build:extension
npm run package:extension
```

Arquivo gerado:

```text
dist/markpin-companion-beta.zip
```

Antes de submeter à Chrome Web Store, configure o endereço exato da aplicação:

```bash
MARKPIN_DEFAULT_URL="https://SEU_USUARIO.github.io/SEU_REPOSITORIO/" \
MARKPIN_WEB_MATCH="https://SEU_USUARIO.github.io/SEU_REPOSITORIO/*" npm run build:extension
npm run package:extension
```

Consulte [`apps/extension/README.md`](apps/extension/README.md), [`docs/COMPANION_INSTALLATION.md`](docs/COMPANION_INSTALLATION.md) e [`docs/CHROME_WEB_STORE.md`](docs/CHROME_WEB_STORE.md).

## GitHub Pages

Somente o workflow `.github/workflows/pages.yml` está habilitado. Os workflows de CI e empacotamento da extensão foram movidos para `.github/workflows-disabled/` e não são executados pelo GitHub Actions.

1. Crie um repositório no GitHub e envie o projeto.
2. Em **Settings → Pages**, selecione **GitHub Actions** como source.
3. Use `main` como branch principal.
4. Opcionalmente, crie a variável de Actions `VITE_COMPANION_URL` com o link não listado da Chrome Web Store.
5. O push em `main` fará build e deploy automaticamente.

O workflow define o `VITE_BASE_PATH` com o nome do repositório, permitindo publicação em:

```text
https://SEU_USUARIO.github.io/SEU_REPOSITORIO/
```

## PWA

Mesmo que a experiência web seja o foco, o build também gera:

- manifesto instalável;
- ícones normais e maskable;
- Service Worker;
- cache offline;
- atalhos para nova nota e AI Inbox;
- aviso de atualização disponível.

A PWA é opcional: o site funciona normalmente sem instalação. Quando o navegador liberar o evento de instalação, o botão aparece no topo e nas Configurações. Depois de instalada, ela abre em janela própria e mantém o funcionamento offline.

## MarkPin Action Protocol

Ações suportadas:

- `notes.create`
- `notes.append`
- `notes.replace`
- `notes.addTags`
- `notes.upsertExternal` — mantém uma única nota por conversa, pesquisa, caixa diária ou outra fonte externa

A documentação pública fica em:

```text
/llms.txt
/ai-instructions.md
/.well-known/markpin.json
```

Exemplo:

```json
{
  "protocol": "markpin-action/v1",
  "id": "action-UUID",
  "operation": "notes.create",
  "actor": {
    "type": "ai",
    "client": "chatgpt"
  },
  "input": {
    "title": "Planejamento",
    "content": "# Planejamento\n\nConteúdo",
    "tags": ["projeto"],
    "folder": "Projetos"
  }
}
```

Consulte [`docs/PROTOCOL.md`](docs/PROTOCOL.md).

## Dependências

As versões foram fixadas exatamente no `package.json` e no `package-lock.json`. Na criação deste MVP foram usadas as versões estáveis atuais em 27 de junho de 2026, incluindo React 19.2.7, Vite 8.1.0 e TypeScript 6.0.3.

Política de atualização:

- Dependabot semanal.
- Sem merge automático de majors.
- `npm ci --ignore-scripts` obrigatório.
- auditoria de vulnerabilidades obrigatória;
- verificação de scripts de instalação;
- testes, typecheck e builds obrigatórios.

## Limitações atuais

- Document Picture-in-Picture possui melhor suporte em Chromium.
- A extensão beta atende Chrome desktop primeiro.
- Inserção de imagem usa Data URL no MVP; o próximo passo é um gerenciador de assets OPFS.
- A busca completa carrega documentos para um Worker; um índice incremental será necessário para bibliotecas muito grandes.
- Ainda não há sincronização entre dispositivos.
- O modo pasta local pela File System Access API está planejado, mas não foi incluído nesta primeira entrega.
- Mermaid, fórmulas, edição tabular e backlinks completos estão no roadmap.

## Documentação

- [Arquitetura](docs/ARCHITECTURE.md)
- [Protocolo de IA](docs/PROTOCOL.md)
- [Publicação da extensão](docs/CHROME_WEB_STORE.md)
- [Segurança de dependências](docs/DEPENDENCY_SECURITY.md)
- [Roadmap](docs/ROADMAP.md)
- [Privacidade](PRIVACY.md)
- [Segurança](SECURITY.md)

## Licença

MIT. Consulte [LICENSE](LICENSE).