Blocos (.lnb)

Um bundle de Blocos é uma pasta cujo nome termina em .lnb, tratada como um item único na árvore (duplo clique abre). Cada bloco é um arquivo real no disco; a ordem fica num blocks.json na raiz do bundle. É como um caderno: células empilhadas de código ou texto. Um notebook Jupyter entra por aqui: clique com o botão direito num .ipynb na árvore e escolha Importar como Blocos (.lnb). Cada célula vira um arquivo real — versionável e lido pela busca —, e o .ipynb continua onde estava, porque importar não é converter. As saídas gravadas no notebook não vêm junto: executar a célula aqui gera o resultado de verdade, com instante e comando. Se o blocks.json estiver ilegível (um conflito do Git ou uma gravação interrompida), o caderno avisa e não o regrava: a ordem, a conexão e a sessão só voltam a ser gravadas depois que você o corrigir.

Células, barra do caderno e atalhos

Cada célula tem nome, botão de tipo (markdown, python, javascript, sql, shell, powershell, bat, r, julia, http, ia, mermaid, latex e os de texto) e botões para copiar, incluir (clique: abaixo; a setinha: acima e duplicar), apagar, mover para cima e para baixo e executar (a setinha oferece Executar até aqui). A célula nova herda o tipo da vizinha. O botão da direita recolhe a célula, deixando só a primeira linha no cabeçalho, e o contador [n] diz a ordem em que as células rodaram nesta sessão. Crie um caderno pela árvore (Novo) ou em Arquivo → Novo.

A barra do caderno, no topo, age sobre o caderno inteiro: Executar tudo roda as células de código na ordem; Parar interrompe a que está rodando e esvazia a fila (a execução vai ao histórico com saída -1); Limpar saídas fecha os painéis sem apagar nada; o menu Mais exporta o caderno e apaga o histórico. A chave timeoutSec do blocks.json dá um tempo limite por célula (0, o padrão, é sem limite).

Atalhos, com o foco na célula: Ctrl+Enter executa e fica; Shift+Enter executa e vai para a próxima (na última, cria uma nova); Alt+Enter executa e insere uma célula logo abaixo. Numa célula de texto, executar é renderizar: ela abre renderizada quando tem conteúdo, e um duplo clique (ou Enter sobre ela) volta a editar.

Resultado gravado, anexos e histórico

O resultado fica gravado (como num caderno de laboratório): ao terminar, cada execução vira um arquivo .md dentro de saida/<célula>/, no próprio bundle — com o instante, o código de saída, a duração, o comando e a saída em si. Como é Markdown, dá para ler em qualquer editor, versionar no Git junto do caderno e recuperar pela busca nas notas. Reabrir o bundle traz de volta a faixa Última execução acima do painel: clique nela para ver o resultado sem rodar de novo.

Anexos: cada execução recebe uma pasta própria, ao lado do .md, e o caminho dela chega ao programa na variável de ambiente LN_RUN_DIR. O que a célula gravar ali — um gráfico do matplotlib, um CSV — aparece abaixo da saída (imagens desenhadas, o resto como link para a pasta) e fica listado no arquivo do histórico. Saída que já é Markdown (a tabela de um SELECT, a resposta da IA, um diagrama) abre renderizada; o botão Texto/Renderizar da faixa alterna.

Histórico: o botão Histórico ao lado dessa faixa lista as execuções anteriores daquela célula (instante e código de saída) — útil para comparar o que a mesma célula devolveu ao longo do tempo. Guardamos as 10 mais recentes por célula; para mudar, edite a chave historyLimit no blocks.json do bundle (0 desliga a gravação, e com ela os anexos). Saída muito grande é cortada (o arquivo diz truncated: true). Renomear a célula ou trocar seu tipo leva o histórico junto; apagar a célula manda o histórico para a Lixeira.

Sessão persistente

Por padrão cada célula é um processo novo: o que uma define, a seguinte não vê. Com a sessão persistente ligada (botão Sessão da barra; a chave session do blocks.json), as células de Python, JavaScript, shell e PowerShell rodam num processo que fica vivo entre execuções — variáveis, funções e importações de uma célula valem nas seguintes, como no Jupyter. Em Python, as figuras do matplotlib abertas ao fim da célula são gravadas sozinhas na pasta de anexos. Reiniciar sessão esquece tudo; Parar também, porque interromper é encerrar o processo. Em JavaScript, declare com var (ou sem declaração): let, const e class no topo não podem ser declarados de novo — nem rodando a mesma célula outra vez.

Células SQL

Sem conexão apontada, a célula sql roda no DuckDB do próprio caderno (em memória): tabelas criadas numa célula valem nas seguintes, e read_csv('dados/vendas.csv') lê os arquivos da pasta do caderno — guarde os dados numa subpasta, porque cada arquivo solto na pasta do caderno é uma célula. Para um banco de verdade, aponte o caderno para uma conexão .lnc pela barra de conexão (ela lista as conexões do espaço): as células passam a executar no banco, pela mesma conexão do painel Conexões — senha lembrada, túnel SSH, releitura do .lnc e a confirmação de produção antes de qualquer escrita. O resultado de um SELECT vira uma tabela no arquivo de saída; INSERT/UPDATE e afins reportam quantas linhas mudaram, e um erro interrompe o script e registra a instrução que falhou. Trazemos até 100 linhas por consulta (sqlMaxRows no blocks.json; o arquivo avisa quando há mais).

@set nome = valor define uma variável com escopo de caderno, e :nome (ou ?) é um parâmetro perguntado na execução, como no editor SQL. O último SELECT também grava resultado.csv na pasta de anexos (as mesmas linhas da tabela, até o sqlMaxRows), e as células seguintes recebem o caminho em LN_LAST_SQL — em Python, pd.read_csv(os.environ["LN_LAST_SQL"]). A conexão fica no blocks.json como caminho relativo; um .lnc guardado dentro do bundle conta como configuração, não vira célula.

HTTP, IA, Mermaid e LaTeX

Quatro tipos rodam pelo próprio LightNote, sem interpretador: a célula http é um teste .lnh executado pelo mesmo executor do testador (o relatório vai ao histórico; o ambiente é o da chave httpEnv do blocks.json, e um arquivo que a requisição envia tem de estar dentro do espaço); a célula ai manda o prompt ao assistente padrão com o contexto do caderno — a fonte das células anteriores e a última saída de cada uma, menos as células http, que podem levar credenciais —, e a resposta chega renderizada; as células mermaid e latex desenham o diagrama ou a fórmula numa imagem nos anexos. Parar cancela as duas primeiras.

Exportar o caderno

O menu Mais da barra exporta o caderno inteiro: como Markdown (as células de texto inline, o código em cercas com a linguagem, a última saída logo abaixo e as imagens ligadas) ou como notebook Jupyter (.ipynb, com a última saída de cada célula e as imagens embutidas; célula de outra linguagem leva a marca que o VS Code lê). É uma cópia para compartilhar — o caderno continua sendo a pasta.