Fireworks Open ELI5

O que Fireworks Open ELI5 faz?

Transforme um sistema difícil em uma história visual verdadeira. Produza primeiro um spec JSON portátil, depois um explicador HTML autocontido e determinístico.

Limite intransponível

• A evidência vem antes do polimento visual. Rotule cada item de evidência como verified, inferred ou analogy.
• Nunca faça uma analogia parecer verdade de implementação.
• Um arquivo HTML local gerado é apenas generated. Não é published, enviado, transmitido ou verificado quanto ao destino.
• Não publique, envie, transmita ou altere o acesso sem a solicitação explícita do usuário e a verificação própria do fluxo de trabalho de destino.
• A renderização não realiza chamadas de rede. Uma URL citada é um link voltado para o leitor, não uma dependência em tempo de execução. A ação opcional de Páginas nativas pode chamar apenas o helper de mesma origem agrupado em 127.0.0.1; nunca deve contatar um serviço remoto.
• O histórico local do navegador, favoritos e anotações são desabilitados até que o leitor opte por ativá-los. Eles são estado de conveniência, não evidência e nunca modificam o spec fonte ou o artefato gerado.
• Descreva o histórico precisamente como explicadores de mesma origem abertos anteriormente naquele navegador. Nunca afirme que ele enumera todos os arquivos gerados.
• A exportação em PDF invoca a caixa de diálogo de impressão do navegador. PNG exporta uma cena; PPTX e DOCX compatível com Pages exportam uma cena por slide ou página. A saída nativa .pages é permitida somente depois que o aplicativo Pages instalado realmente a salvar; nunca renomeie um DOCX para .pages. Os downloads gerados são apenas artefatos locais.

Fluxo de trabalho

1. Identifique o público, a pergunta, o idioma e uma coisa que deve percorrer a história: uma solicitação, pacote, decisão, evento ou ação do usuário.

2. Escolha exatamente uma gramática de história:

   • concept: intuição → mecanismo → limite.
   • module: ponto de entrada → transformações → saídas/dependências.
   • tradeoff: objetivo compartilhado → opções concorrentes → consequências/regra de decisão.
   • incident: caminho normal → quebra e propagação → detecção/recuperação.

3. Reúna evidências. Para trabalho em repositório, inspecione arquivos reais e use caminhos locais. Para afirmações externas, use fontes autoritativas quando disponíveis. Registre incertezas explicitamente.

4. Crie um spec JSON versão 1 seguindo references/spec-contract.md. Use 3 a 7 cenas, 2 a 6 nós por cena, uma escada da verdade completa, rastreamento, glossário, teach-back, mapa de evidências e o modeData específico do modo obrigatório. Adicione informações de falha aos nós consequentes.

5. Valide antes de renderizar:

   node scripts/validate.mjs path/to/spec.json
   

6. Renderize para um novo arquivo local:

   node scripts/render.mjs path/to/spec.json path/to/explainer.html
   

   O renderizador recusa um caminho existente. Somente quando o usuário explicitamente deseja substituir um arquivo regular conhecido, acrescente --force. A renderização forçada usa uma substituição atômica e ainda recusa links simbólicos e caminhos que não são de arquivos.

7. Valide o spec e o artefato juntos:

   node scripts/validate.mjs path/to/spec.json path/to/explainer.html
   

8. Quando o acesso ao navegador estiver disponível, inspecione o artefato local na largura desktop e em 390px. Confirme um h1, rótulos legíveis, sem estouro horizontal, foco do teclado, tablists independentes, reprodução global e local por cena, acompanhamento da viewport, sincronização ativa de bordas reais e cartões de evidência, fases de animação de entrada/manter/saída, lente de falha, revelação de respostas e zero solicitações de recursos remotos. Cada cartão de evidência de cena deve expor seu status, base central concisa, escopo de suporte e uma URL ou limite explícito de "sem localizador".

9. Exercite o espaço de trabalho do leitor: abra e dispense o drawer modal com mouse e teclado; confirme o retorno do foco; ative a biblioteca intencionalmente; recarregue e verifique favoritos e uma anotação em texto simples; e confirme que o histórico contém apenas explicadores de mesma origem que foram realmente abertos. Use uma anotação em formato de marcação para verificar que ela permanece como texto inerte.

10. Exercite a exportação: confirme a folha de estilo de impressão, a assinatura e dimensões PNG, as assinaturas ZIP do PPTX e DOCX e as partes OOXML obrigatórias, e o link de download alternativo quando os downloads automáticos são suprimidos. Visualmente confirme que a arte da cena inclui um rodapé de evidência limitado com status, base central e localizador de fonte ou limite. Quando Pages nativo estiver no escopo, execute o scripts/serve.mjs, verifique se o pacote .pages contém Index/Document.iwa, e então reabra-o no Pages. Corrija o spec ou template e execute novamente ambos os validadores após qualquer alteração.

Idioma do relatório

• Escreva o relatório final de QA, status, handoff e artefato gerado no idioma da solicitação substantiva mais recente do usuário por padrão.
• Uma solicitação explícita de idioma do relatório substitui esse padrão.
• spec.language controla apenas a interface do explicador gerado; ele não força o idioma do relatório da conversa.
• Em conversas com vários idiomas, ignore saudações curtas ao escolher o idioma do relatório. Preserve código, comandos, caminhos, identificadores, erros exatos e títulos de fontes quando a tradução reduziria a precisão.

Leia references/reporting.md para o contrato completo de seleção de idioma e relatório de entrega.

Regras de construção da história

• Escreva o título como uma promessa concreta, não um rótulo de categoria.
• Mantenha o resumo em uma frase e cada nó em uma responsabilidade.
• Prefira 3 a 5 cenas. Use 6 a 7 apenas quando omitir um estágio distorceria a causalidade.
• Arestas são relacionamentos ou ações. Use verbos curtos nos rótulos.
• O rastreamento deve visitar IDs de nós reais em uma ordem significativa.
• Use dados de falha apenas quando o impacto, sintoma visível e plano de contingência são conhecidos.
• Mantenha a camada simples precisa o suficiente para sobreviver à camada técnica.
• Coloque limitações em truthLadder.caveat, não em avisos minúsculos.
• Use IDs de fonte nas cenas ou nós que eles suportam.
• Não cite uma fonte meramente porque ela está adjacente à afirmação.

Leia references/story-grammars.md para padrões de modo, references/evidence-rules.md para limites de afirmação, e references/visual-system.md antes de alterar a linguagem visual do renderizador. Leia references/library-and-export.md antes de alterar persistência, navegação, reprodução ou comportamento de exportação.

Portão de qualidade

O trabalho está pronto como artefato local apenas quando:

• o validador retorna ok: true para o spec e o HTML renderizado;
• todos os IDs e referências são resolvidos;
• toda seção interativa obrigatória tem conteúdo;
• o modo de história selecionado passa seu próprio contrato semântico;
• o HTML é determinístico e carrega o meta-tag SHA-256 do spec;
• o artefato corresponde em bytes ao spec fornecido e usa hashes CSP confiáveis;
• o artefato não tem recursos externos, APIs de tempo de execução inseguras ou fontes remotas;
• o estado persistido do leitor é opt-in, com namespace, limitado, de mesma origem e mantido fora do hash determinístico do spec;
• as anotações são renderizadas apenas como texto e não podem criar marcação executável;
• a reprodução global e local compartilham uma máquina de estados e nunca são executadas juntas;
• cada etapa do rastreamento ativa o caminho de relacionamento de saída real (ou o caminho de entrada de um sink), mantém o rótulo e o estado da seta alinhados, e destaca apenas a evidência que suporta aquela etapa;
• os cartões de evidência de cena preservam os limites verified/inferred/analogy e expõem texto central mais um localizador acionável sem buscar visualizações remotas;
• os pacotes de cena PNG, PPTX e DOCX têm as assinaturas e estrutura esperadas e contêm seu rodapé de evidência; uma exportação nativa do Pages também foi reaberta no Pages;
• mobile usa o fluxo empilhado em vez de encolher o SVG desktop;
• o relatório final segue o idioma de interação atual do usuário, nomeia os caminhos do spec e do HTML gerados, e informa se foram executados QA de desktop, mobile, persistência, reprodução, evidência e exportação do navegador.

Se a evidência estiver incompleta, gere apenas quando o mapa de evidências e a ressalva tornarem a lacuna inequívoca. Caso contrário, pare e reporte a evidência ausente.