PhotonJS

O renderer web do Photon — um sistema de UI cross-platform. Um framework full-stack estilo Next.js, sem React, com composição de UI inspirada no Flutter (Stateless/Stateful, composite pattern), escrito para TypeScript 7 e Bun, com um motor auxiliar em Go (imagens, compressão, cache).

Status: 🏗️ Fase 0 — esqueleto do monorepo no lugar (workspaces Bun, @photon/tokens com os tokens do design system, engine Go stub, CI com tsgo/Biome/testes). Núcleo reativo (Fase 1) a seguir.

Photon é cross-platform. O equantic-ui é o renderer mobile (motor nativo); PhotonJS é o renderer web (DOM + CSS). Os dois compartilham o design system (tokens), o inventário de componentes e a API de Component.

A ideia em uma frase

Você descreve a UI compondo components em TypeScript puro — sem JSX, sem React — do mesmo jeito que descreveria uma tela no Flutter. O PhotonJS reconcilia essa árvore em DOM real no cliente e em HTML no servidor, com roteamento por arquivos, design system, otimização de imagens e cache de primeira classe.

class Counter extends StatefulComponent {
  createState() { return new CounterState(); }
}

class CounterState extends State<Counter> {
  count = signal(0);

  build(context: BuildContext): Component {
    return Row({
      gap: Space.S3,
      children: [
        // valor reativo: thunk. Muda o sinal → só este texto atualiza (sem re-build).
        Text(() => `Contagem: ${this.count.value}`),
        Button({ label: "+1", onPressed: () => this.count.value++ }),
      ],
    });
  }
}

Pilares de design

Pilar	Decisão
Modelo mental	Flutter: StatelessComponent / StatefulComponent, build(context), BuildContext, Key
Reatividade	Sinais de granularidade fina (signal/computed/effect), modelo build-once — muda o valor, muda só o nó ligado
Padrão central	Composite (GoF) — tudo é Component; folhas e composições implementam a mesma interface
Design system	Tokens do Photon (cores/tipo/espaço/raio/elevação) compartilhados com o mobile equantic-ui
Linguagem de UI	TypeScript puro, factory functions + classes. Zero JSX, zero template string
Runtime / bundler	Bun (servidor, transpile, bundle, package manager, testes)
Type-checking	TypeScript 7 (tsgo, compilador nativo em Go — ~10x mais rápido)
Motor auxiliar	Go (photon-engine): imagens, compressão, cache endereçado por conteúdo
Roteamento	Baseado em arquivos (app/), com layouts aninhados e rotas dinâmicas
Renderização	Ilhas primeiro (partial hydration); SSG/SSR/ISR por rota; full hydration como opt-in
Estilo	Props tipadas de widget → CSS atômico extraído em build (zero-runtime, cacheável)

Documentos

• docs/ARCHITECTURE.md — arquitetura completa, com esboços de API e decisões.
• docs/LOOK-AND-FEEL.md — a sintaxe real: um app de exemplo (board de tarefas) com Component, sinais, ilhas e tokens.
• docs/ENGINE.md — o motor Go (photon-engine): protocolo JSON-RPC, pipeline de imagem, chave de cache, distribuição.
• docs/COMPONENT-ANATOMY.md — anatomia de um componente (Button/TextInput): props → tokens → HTML+CSS atômico emitido.
• docs/SERVER-CLIENT.md — fronteira servidor/cliente: dois grafos, serialização do loader → sinal, marcadores de hidratação.
• docs/REACTIVITY.md — o motor reativo por dentro: sinais, auto-tracking, ownership, For keyed, no-op no SSR.
• docs/ROADMAP.md — plano de execução em fases, com marcos e critérios de aceite.
• docs/decisions/ — ADRs (registros de decisão):
  • ADR 0001 — linguagem e tooling (.ts, não .phts)
  • ADR 0002 — convenção de nomes de arquivo (nome.papel.ts, estilo NestJS)

Por que não React?

Porque o objetivo é um modelo mental declarativo-composicional à la Flutter, com controle total sobre a reconciliação, a fronteira servidor/cliente e o pipeline de assets — e um runtime próprio, enxuto, sem a bagagem histórica do React. Ganhamos: hot reload preservando estado (como o Flutter), hidratação parcial nativa, CSS atômico sem runtime e um motor Go acoplado para imagens/cache.