# Criar um molde para a Cadernita Este documento é a especificação completa de um molde, e serve a dois usos: - **um agente o busca sozinho** em `https://cadernita.com/criar-moldes.md`, quando alguém pede "crie um molde de X para o cadernita.com". Quem pede não precisa ter o código, nem entregar documento nenhum; - **ou uma pessoa o cola inteiro** num assistente, seguido da descrição do molde. Ele traz tudo que o validador exige — e o validador é rigoroso, então um molde escrito de memória quase sempre é recusado. --- ## Primeiro passo: leia três moldes de fábrica **Antes de desenhar qualquer coisa, abra [`https://cadernita.com/moldes.md`](https://cadernita.com/moldes.md), escolha três moldes e leia as fichas deles.** Não é leitura opcional, e não é para depois: é o passo que decide a forma do que você vai escrever. O motivo é este. Este documento diz o que o validador **recusa**, e nada mais — seguir só ele leva sempre à forma mais barata que passa, uma linha curta em cima e um campo de texto embaixo, com os moldes do pacote se distinguindo apenas pelo `placeholder`. Os trinta e três moldes de fábrica da Cadernita são o contrário disso: uma semana em grade, um bitmap escrito à mão, duas vozes que se alternam, alternativas lado a lado, uma foto composta. Cada ficha traz o código inteiro do molde e o comentário de projeto de quem o fez. Escolha assim: **dois pelo parecido** — os moldes cujo uso mais se aproxima do que vão te pedir — e **um pelo estranho**, que não tenha nada a ver, para ver do que um molde é capaz. E não se inspire nos pacotes que estiverem no `inbox/` de alguém: foram escritos por outro agente que também não tinha o que ler, e copiar de lá multiplica a mesma forma pobre. --- ## O que você vai produzir Você vai escrever um **pacote de moldes da Cadernita**: um único arquivo JSON. A Cadernita é um caderno digital. Uma *nota* nasce de um *molde* — um pequeno formulário com aparência e comportamento próprios. O molde é a caneta; a nota é o que fica escrito. O núcleo do aplicativo **nunca interpreta o conteúdo**: ele só sabe que todo valor editável é um campo de formulário com um `name` estável. Responda **somente com o JSON**, sem cercas de código e sem explicação em volta. ## O formato do arquivo ```json { "format": "cadernita-package", "version": 1, "id": "meu-pacote", "name": "nome legível do pacote", "revision": 1, "molds": [ { "id": "meu-molde", "name": "nome curto que aparece no seletor", "hint": "uma linha dizendo para que serve", "paper": "#eef0e6", "ink": "#26231f", "size": "content", "html": "…", "css": "…", "js": "…" } ], "palettes": [ { "id": "minha-paleta", "name": "nome da paleta", "hint": "quando usar esta paleta", "entryStageId": "inicio", "stages": [ { "id": "inicio", "templateId": "meu-molde", "afterCommit": "inicio", "onEscape": "segundo" }, { "id": "segundo", "templateId": "meu-outro-molde", "afterCommit": "segundo", "onEscape": "inicio" } ] } ] } ``` Regras do envelope: - todo `id` casa com `^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$` — minúsculas, números e hífen - `revision` é inteiro positivo — veja "corrigir é uma revisão nova" adiante - `paper` e `ink` são cores CSS simples (`#rrggbb`); são o fundo e a tinta da nota - `size` é um de `full`, `attached`, `content`, `grows` (explicados adiante) - `html`, `css` e `js` vão como **strings JSON** — escape as aspas e use `\n` - cada fonte tem no máximo 240.000 caracteres; o pacote inteiro, 1.000.000 bytes - em `stages`, `templateId` é o **id simples** do molde (`"meu-molde"`), e não o id prefixado — a Cadernita monta o `local:pacote:molde` sozinha ao instalar - `afterCommit` é a etapa que vem depois de guardar, e `onEscape` é a que vem ao apertar Esc — veja a regra padrão logo abaixo, porque errá-la deixa moldes inalcançáveis Campos opcionais do molde: - `"attachesToPrevious": true` — a nota cola visualmente na anterior - `"remembers"` e `"rememberAfterCommit"` — veja "a memória do molde" adiante ## Como ligar as etapas — a regra padrão **Siga esta regra salvo se pedirem outra coisa.** Controlar o fluxo à mão é recurso avançado, e quase toda paleta quer só isto: - **uma etapa por molde** da paleta; - **`afterCommit` aponta para a própria etapa** — guardar uma nota deixa você no mesmo molde, pronto para escrever outra igual; - **`onEscape` aponta para a etapa seguinte**, e a última volta para a primeira. `Esc` é o que troca de molde, e o anel é o que faz isso funcionar. Com quatro moldes: ```text ┌──────────────────────────────────────────┐ ▼ │ molde-a ──esc──► molde-b ──esc──► molde-c ──esc┘ ▲ │ └─┘ guardar (afterCommit) ``` **Um molde sem etapa não aparece na paleta.** Ele ainda pode ser alcançado pela paleta "todos", que lista o catálogo inteiro, mas a paleta que você escreveu não o mostra — e é o erro mais fácil de cometer, porque o validador não o recusa. Uma paleta de **uma etapa só** é um caso legítimo, mas saiba o que ela significa: `Esc` não tem para onde ir e deixa de trocar de molde. Se quiser um molde avulso, aponte o `onEscape` dele para uma etapa de outro molde do pacote. ## A nota mostra tudo — a regra que mais importa **Uma nota guardada tem que caber inteira na tela, sem rolagem por dentro.** Não é gosto. A nota guardada é desenhada pelo **mesmo molde**, e ela não rola: para não roubar a rolagem da fita, a nota guardada ignora o ponteiro. Então qualquer coisa que sobre de uma barra de rolagem interna fica **invisível para sempre** — o texto está lá, e ninguém consegue lê-lo. Além disso a fita já é uma rolagem. Um molde que rola cria um segundo scroll aninhado no primeiro, e no celular esse gesto vira uma disputa entre os dois. Na prática: prefira o molde crescer a limitar a altura. Não escreva `max-height`, `overflow: auto` nem `overflow: scroll` num campo de escrita. ## Os quatro tamanhos O molde declara quanto espaço ocupa, e **uma única região cede** — a que levar a classe `mold__yield`. Ponha essa classe no campo que absorve a sobra, quase sempre o `textarea` principal; sem ela o molde não sabe onde ceder. - **`grows`** — cresce com o texto e empurra a nota junto. **É o certo para qualquer molde com prosa, e é o que você quer na dúvida.** Dos 33 moldes de fábrica da Cadernita, 18 são `grows`. - `content` — a altura é a do conteúdo. Para molde de campos **curtos e limitados**: um título, uma escolha, uma data. Só 4 moldes de fábrica o usam. - `full` — ocupa a faixa inteira de escrita. Para **instrumento de composição fixa**: uma foto, uma grade de semana, um quadro, uma busca. - `attached` — para continuação, junto com `attachesToPrevious`. ## A memória do molde **Todo molde já guarda rascunho, sem você declarar nada.** Sair de um molde, escrever noutro e voltar devolve o que estava escrito. Não use `remembers` para isso: já é de graça. O que `remembers` controla é o **depois de guardar**: - sem ele, guardar limpa o molde e você começa a próxima nota em branco; - `"remembers": true` — os valores **sobrevivem ao guardar** e continuam ali; - `"rememberAfterCommit": ["materia", "professor"]` — só esses campos sobrevivem, e o resto limpa. É o que faz um molde de aula manter a matéria e esquecer o apontamento. E `contexto.onMemoryChange()` serve para quando **o seu JavaScript** muda valores por conta própria: avise, e o rascunho acompanha. Digitação não precisa — ela já é observada. ### A pegadinha Um molde que declara `remembers` **não recebe `contexto.onCommit`**, e um que não declara **não recebe `onMemoryChange`**. São exclusivos. Se o seu molde precisa pedir para guardar a partir do JavaScript, ele não pode declarar `remembers`. ## Ver a fita O molde pode olhar as notas que estão à vista. Não vem pelo `contexto`: vem pelo próprio documento, como uma lista escondida — a mesma ideia do `data-export`, um molde que precisa ver o caderno o vê **olhando a tela**. ```js const marcas = [...document.querySelectorAll('#cadernita-ribbon article')]; for (const marca of marcas) { marca.dataset.noteId; // identidade da nota marca.dataset.noteAt; // quando foi escrita, ISO marca.dataset.noteTemplate; // de qual molde nasceu marca.dataset.noteTags; // as tags, separadas por espaço marca.dataset.noteSize; // quanto foi escrito, em caracteres } ``` Três coisas que precisam ficar claras: **É metadado, nunca o conteúdo.** O núcleo da Cadernita não interpreta o que está escrito nas notas, e um molde também não recebe. Ainda dá para fazer bastante: contar notas de um molde, medir ritmo pelas datas, somar o tamanho escrito, agrupar por tag. **É o que está à vista**, não o caderno inteiro — o recorte de tags atual. Trocar de caderno muda a lista. **Ela se atualiza sozinha** enquanto o molde está aberto: guardar uma nota mexe na lista na hora. Mas o seu JavaScript roda uma vez só — para acompanhar, observe a lista, senão o número congela no que era quando o molde abriu: ```js const fita = document.getElementById('cadernita-ribbon'); const olho = new MutationObserver(contar); olho.observe(fita, { childList: true }); return () => olho.disconnect(); ``` Já uma nota **guardada** recebe a fita de quando ela foi escrita e não muda mais — é registro, não painel. Por isso vale sair cedo em `contexto.locked`. ## O HTML O molde roda dentro de um `