openpencil/packages/docs/it/development/contributing.md

Contribuire

Struttura del progetto

packages/
  core/              @open-pencil/core — motore (zero dipendenze DOM)
    src/             Grafo scena, renderer, layout, codec, kiwi, tipi
  cli/               @open-pencil/cli — CLI headless per operazioni .fig
    src/commands/    info, tree, find, export, eval, analyze
  mcp/               @open-pencil/mcp — server MCP per strumenti IA
    src/             Trasporti stdio + HTTP (Hono), 87 strumenti
src/
  components/        Vue SFCs (canvas, pannelli, barra strumenti, selettore colore)
    properties/      Sezioni pannello proprietà (Aspetto, Riempimento, Contorno, ecc.)
  composables/       Input canvas, scorciatoie tastiera, hook di rendering
  stores/            Stato editor (reattività Vue)
  engine/            Shim di ri-esportazione da @open-pencil/core
  kiwi/              Shim di ri-esportazione da @open-pencil/core
  types.ts           Tipi condivisi (ri-esportati da core)
  constants.ts       Colori UI, default, soglie
desktop/             Tauri v2 (Rust + config)
tests/
  e2e/               Regressione visiva Playwright
  engine/            Test unitari (bun:test)
docs/                Sito documentazione VitePress
  specs/             Specifiche di capacità (fonte di verità)
  changes/           Cambiamenti attivi e archiviati

Configurazione sviluppo

bun install
bun run dev          # Editor su localhost:1420
bun run docs:dev     # Docs su localhost:5173

Stile di codice

Strumenti

Strumento	Comando	Scopo
oxlint	bun run lint	Linting (basato su Rust, veloce)
oxfmt	bun run format	Formattazione codice
tsgo	bun run typecheck	Verifica tipi (checker TypeScript basato su Go)

Eseguire tutte le verifiche:

bun run check

Convenzioni

• Nomi file — kebab-case (scene-graph.ts, use-canvas-input.ts)
• Componenti — PascalCase Vue SFCs (EditorCanvas.vue, NumberField.vue)
• Costanti — SCREAMING_SNAKE_CASE
• Funzioni/variabili — camelCase
• Tipi/interfacce — PascalCase

Convenzioni per agenti IA

Sviluppatori e agenti IA dovrebbero leggere AGENTS.md nella root del repo (vedi su GitHub). Copre rendering, grafo scena, componenti e istanze, layout, UI, formato file, convenzioni Tauri e problemi noti.

Apportare modifiche

3. Implementare il cambiamento
4. Eseguire bun run check e bun run test
5. Inviare una pull request

File chiave

Il codice sorgente del motore core si trova in packages/core/src/. Il codice specifico dell'app per editor, documenti, IA, collaborazione, shell, demo e automazione vive in src/app/*; l'SDK Vue contiene il codice canvas e composable riutilizzabile in packages/vue/src/.

File	Scopo
packages/scene-graph/src/	Grafo scena: nodi, variabili, istanze, hit testing e annullamento
packages/core/src/canvas/renderer.ts	Pipeline di rendering CanvasKit
packages/core/src/layout/	Adattatore layout Yoga
packages/core/src/clipboard.ts	Appunti compatibili con Figma
packages/core/src/vector/	Modello rete vettoriale
packages/core/src/io/formats/raster/render.ts	Export immagine offscreen (PNG/JPG/WEBP)
packages/kiwi/src/schema-runtime/	Runtime dello schema e codec binario Kiwi
packages/fig/src/node-change/	Conversione tra SceneGraph e Figma NodeChange
packages/core/src/io/formats/fig/	Orchestrazione lettura/scrittura .fig per l'app
packages/cli/src/index.ts	Punto di ingresso CLI
packages/core/src/tools/	Definizioni strumenti unificate (IA, MCP, CLI)
packages/core/src/figma-api/	Implementazione Figma Plugin API
packages/mcp/src/server.ts	Factory del server MCP
packages/cli/src/commands/	Comandi CLI (info, tree, find, export, eval, analyze)
src/app/editor/session/create.ts	Editor session assembly
packages/vue/src/canvas/CanvasRoot.vue	Composable rendering canvas
packages/vue/src/canvas/useCanvasInput.ts	Gestione input mouse/touch
src/app/shell/keyboard/use.ts	Gestione scorciatoie tastiera