Danila Poyarkov 6545f20c53

Refactor architecture boundaries across core, app, and packages (#234 )

* refactor(core): decompose editor factory and action modules

Split the monolithic editor factory and large action modules into focused
domain helpers:

- create.ts assembles context through bridge modules (clipboard,
  components, structure, undo) and delegates to graph-reads, graph-events,
  layout-runner, component-sync, and state factory
- structure.ts delegates to group, container-wrap, auto-layout-wrap,
  reorder, and state-toggle helpers
- selection.ts delegates to hit-test, overlays, container navigation,
  and read helpers
- clipboard.ts delegates to subtree-history, images, export, copy,
  fonts, and placement helpers
- shapes.ts delegates to pen actions and section-adopt
- components.ts delegates to focus and instances helpers
- alignment.ts delegates to flip-rotate helper
- text.ts uses explicit TextEditSession for snapshot comparison

New focused modules: nudge, variable-bindings, layout-mode,
page-viewports, tool-registry, color-space

Undo: history/position and history/snapshot helpers, hardened
batch/rollback with nested batch support and configurable limit

* refactor(core): split tool definitions by domain

Split the monolithic tool registry into domain-specific modules:

- read/ — selection, find, pages, fonts, components, nodes, query, jsx
- create/ — basic shapes, components, vector, JSX render
- modify/ — paint, effects, geometry, layout, state, text, update
- structure/ — basic, arrange, batch, hierarchy, replace, tree
- variables/ — bindings, collections, read, values
- vector/ — boolean, path, export, viewport
- analyze/ — colors, typography, spacing, clusters, diff, eval
- describe/ — summaries, tree, roles, layout-issues
- stock-photo/ — providers, requests, apply
- codegen/ — component-map, tokens

Split registry into core/extended tiers; refine schema and AI adapter

* refactor(core): restructure kiwi codec and instance overrides

Reorganize the Kiwi .fig codec into domain subdirectories:

- binary/ — codec, schema, protocol
- fig/ — file, import, parse (core, worker, transfer)
- node-change/ — convert, export-node, serialize, plugin-data
- instance-overrides/ — constraints, dsd, populate, props, resolve,
  symbol-overrides, symbol-props, sync, types

Vendored kiwi-schema/ left isolated

* refactor(core): split profiler, icons, IO, and add subpath exports

Profiler: speedscope-export, capture-session, hud-controller
Icons: api, svg, types, render, create-icons tool
IO: format registry and subpath exports
Canvas/color/text/vector: targeted cleanup

Add deliberate subpath exports: random, xpath, vector, color, canvas,
scene-graph, kiwi, design-jsx, io, tools, editor, layout, canvaskit,
profiler, text, lint, rpc, figma-api, constants

* refactor(vue): decompose canvas input, surface lifecycle, and controls

Canvas surface: gl-surface, kit-loader, render-loop, resize-observer

Canvas input handlers:
- move: drop-target, move-snap, duplicate-drag
- select: select-move, select-hover, select-hit
- resize: resize-rect, resize-vector, resize-start
- transform: rotation, marquee, pan, text-selection
- text-edit: navigation, clipboard, textarea lifecycle
- Shared: click-count, space-key, pan, pan-zoom, draw, raf-scheduler

Editor composition:
- commands split: actions, context, metadata, edit, selection, view
- menu-model split: command-groups, builders, types
- Gradient stop composable reuse in primitive root

Controls: fill, layout, typography, appearance, effects, stroke,
okhcl, prop-scrub, node-props, undo-batch, color-variable-binding
Variables/i18n/document/export helpers

Organize canvas, primitives, controls, editor, and variables into
cohesive module directories with package-local import aliases

Expose MenuActionNode/MenuSeparatorNode from public API

* refactor(app): split document IO, editor session, and automation bridge

Document IO: source-state, naming, writer, reload-source, reload-state,
imported-document, watch-targets, save-targets

Editor session: create, modules, types, accessors, computed, refs
Editor canvas: loader-overlay, collaboration-awareness,
context-selection, menu-actions, menu-model

Automation bridge: eval, tools, exports, files, selection, RPC fallback

AI/ACP: transport, map-update, permission, debug, chat effects/storage
Collab: awareness, graph-bindings, yjs-sync, follow, session, types
Shell keyboard: actions, bindings, clipboard, focus, nudging,
raw-events, registry, reserved, shortcuts, space-tool
Shell menu: app-menu, document-name, entry, files

Demo: colors, effects, helpers, section builders (components,
app-preview, effects, standalone, variables) — document.ts reduced
from 981 to 32 lines as pure orchestrator

Move app modules under src/app/ with organized domain structure:
editor, document, ai, collab, shell, automation, demo, tabs

* refactor(app): decompose UI components with provide/inject context

Split monolithic components using Reka UI-inspired namespace folders
with scoped provide/inject context — no prop drilling:

- CollabPanel/ — context, avatars, share, connected, join
- ColorPickerPanel/ — context, area, format, field groups, sliders
- MobileHud/ — context, action toast, tool badge, file menu, presence
- ProviderSettings/ — context, API key/type, endpoint, tokens, photos
- Toolbar/ — actions, types, desktop, mobile, tool button, flyout
- LayoutSection/ — types, auto-layout, flex, grid, padding, size, clip

Properties helpers: fill-okhcl adapter, fill-label, color-style-row
Menu: entry helpers, document-name rename, stale type removal

* refactor(mcp): split server into focused modules

- browser-rpc — WebSocket client management
- mcp-sessions — session lifecycle
- tool-output — response formatting
- tool-schema — Zod schema generation from ToolDefs
- jsx-preprocess — JSX source transformation
- result — result helpers
- tool-registration — MCP tool wiring
- auth — API key validation
- http-options — CORS/request handling
- stdio-bridge — stdio transport adapter

* refactor(cli): split analyze subcommands and shared helpers

- Analyze subcommands: clusters, colors, spacing, typography
- RPC data loading helper
- Migrate imports to targeted core subpath exports

* refactor(docs): split VitePress config and shared table component

Config helpers: sdk-sidebar, seo, labels, sidebars, locale-theme,
root-theme, locales

Shared SdkDataTable component replaces duplicated table markup in
SdkPropsTable, SdkEventsTable, and SdkSlotsTable

Update contributing and testing docs

* refactor(tauri): decompose desktop entrypoint

Split lib.rs into focused service modules:

- fig_container.rs — .fig archive/compression commands
- fonts.rs — font cache and system font enumeration
- menu.rs — native menu construction
- menu_events.rs — menu event dispatch and devtools toggle
- window.rs — main window show/focus lifecycle

* test: share domain test factories and migrate fixtures

New shared helpers:
- tests/helpers/scene.ts — makeSceneGraph factory
- tests/helpers/vector-network.ts — vertex/segment/network builders
- tests/helpers/fig-traversal.ts — all-node collection, type counts
- tests/helpers/undo.ts — undo test utilities
- tests/helpers/editor-history.ts — editor history test helpers

Migrate render, vector, fig-roundtrip, and undo tests to use shared
factories instead of inline fixture construction

* build: add structural lint rules, split vite config, update docs

Structural lint (oxlint.structure.json + lint/plugin.js):
- 20+ custom rules enforcing package boundaries, lifecycle patterns,
  naming conventions, and import discipline

Vite config split: raw-markdown, canvaskit-assets, pwa, server,
aliases, automation plugins

Remove legacy shims and utils superseded by SDK/core modules
Update AGENTS.md, CONTRIBUTING.md, eval-command docs, tsconfig

* fix(vue): normalize canvas directory casing and remove duplicate export

- Rename Canvas/ to canvas/ in git index to match #vue/canvas/* imports
  (PascalCase was correct for component primitives but canvas/ is a
  non-component domain directory)
- Remove duplicate ./random subpath export in core package.json

* fix: add #vue and #core Vite resolve aliases for dev server

* refactor(core): reduce remaining large modules

Split the remaining large core hotspots into cohesive domain modules while preserving public facades and behavior.

- Extract scene graph types, variables, node defaults, and vector-network helpers
- Decompose canvas renderer orchestration, state, paints, colors, lifecycle, labels, and delegated domain methods into renderer/ and labels/ subfolders
- Split Kiwi node-change, binary variable binding, layout, RPC, vector, JSX export, clipboard, design JSX, and Figma proxy helpers
- Replace collision-driven *Fn import aliases with namespace imports and enforce the pattern in lint

Validation:
- bun run check
- bun --filter @open-pencil/vue build
- bun run test:dupes

* fix(app): forward color input attrs

* fix(app): cover section drawing errors

* fix(editor): undo option-drag duplicates

* docs: document domain subfolder convention

* fix(app): handle undo redo on keydown

* refactor(app): dispatch shortcuts from keydown

* refactor: group prefixed domain modules

* refactor(app): use tinykeys for shortcuts

* refactor(core): group symbol override modules

* refactor(core): group fig kiwi container helper

* refactor(canvas): split overlay rendering modules

* refactor(vue): remove unused internal barrels

* fix(app): lay out demo components before instancing

* fix(app): restore demo badge spacing

* perf(canvas): split scene and overlay rendering

* refactor(vue): wrap wheel gesture lifecycle

* fix(canvas): wait for fonts before hiding loader

* docs: update unreleased changelog

2026-04-30 15:14:19 +03:00

4.3 KiB

Raw Blame History

Contribuer

Structure du projet

packages/
  core/              @open-pencil/core — moteur (zéro dépendance DOM)
    src/             Graphe de scène, renderer, layout, codec, kiwi, types
  cli/               @open-pencil/cli — CLI headless pour opérations .fig
    src/commands/    info, tree, find, export, eval, analyze
  mcp/               @open-pencil/mcp — serveur MCP pour outils IA
    src/             Transports stdio + HTTP (Hono), 87 outils
src/
  components/        Vue SFCs (canevas, panneaux, barre d'outils, sélecteur de couleur)
    properties/      Sections du panneau de propriétés (Apparence, Remplissage, Contour, etc.)
  composables/       Entrée canevas, raccourcis clavier, hooks de rendu
  stores/            État de l'éditeur (réactivité Vue)
  engine/            Shims de ré-exportation depuis @open-pencil/core
  kiwi/              Shims de ré-exportation depuis @open-pencil/core
  types.ts           Types partagés (ré-exportés depuis core)
  constants.ts       Couleurs UI, défauts, seuils
desktop/             Tauri v2 (Rust + config)
tests/
  e2e/               Régression visuelle Playwright
  engine/            Tests unitaires (bun:test)
docs/                Site de documentation VitePress
  specs/             Spécifications de capacités (source de vérité)
  changes/           Changements actifs et archivés

Configuration du développement

bun install
bun run dev          # Éditeur sur localhost:1420
bun run docs:dev     # Docs sur localhost:5173

Style de code

Outils

Outil	Commande	Objectif
oxlint	`bun run lint`	Linting (basé sur Rust, rapide)
oxfmt	`bun run format`	Formatage du code
tsgo	`bun run typecheck`	Vérification de types (checker TypeScript basé sur Go)

Exécuter toutes les vérifications :

bun run check

Conventions

Noms de fichiers — kebab-case (scene-graph.ts, use-canvas-input.ts)
Composants — PascalCase Vue SFCs (EditorCanvas.vue, ScrubInput.vue)
Constantes — SCREAMING_SNAKE_CASE
Fonctions/variables — camelCase
Types/interfaces — PascalCase

Conventions pour agents IA

Les développeurs et agents IA doivent lire AGENTS.md à la racine du repo (voir sur GitHub). Couvre le rendu, le graphe de scène, les composants et instances, le layout, l'UI, le format de fichier, les conventions Tauri et les problèmes connus.

Apporter des changements

Implémenter le changement
Exécuter bun run check et bun run test
Soumettre une pull request

Fichiers clés

Le code source du moteur core se trouve dans packages/core/src/. Le code propre à l'app pour l'éditeur, les documents, l'IA, la collaboration, le shell, les démos et l'automatisation vit sous src/app/*; le SDK Vue contient le code canvas et composable réutilisable dans packages/vue/src/.

Fichier	Objectif
`packages/core/src/scene-graph/`	Graphe de scène : nœuds, variables, instances, hit testing
`packages/core/src/canvas/renderer.ts`	Pipeline de rendu CanvasKit
`packages/core/src/layout.ts`	Adaptateur layout Yoga
`packages/core/src/scene-graph/undo.ts`	Gestionnaire annuler/rétablir
`packages/core/src/clipboard.ts`	Presse-papiers compatible Figma
`packages/core/src/vector/`	Modèle de réseau vectoriel
`packages/core/src/io/formats/raster/render.ts`	Export d'image hors-écran (PNG/JPG/WEBP)
`packages/core/src/kiwi/binary/codec.ts`	Encodeur/décodeur binaire Kiwi
`packages/core/src/kiwi/fig-import.ts`	Logique d'import de fichiers .fig
`packages/cli/src/index.ts`	Point d'entrée du CLI
`packages/core/src/tools/`	Définitions d'outils unifiées (IA, MCP, CLI)
`packages/core/src/figma-api/`	Implémentation de Figma Plugin API
`packages/mcp/src/server.ts`	Factory du serveur MCP
`packages/cli/src/commands/`	Commandes CLI (info, tree, find, export, eval, analyze)
`src/app/editor/session/create.ts`	Editor session assembly
`packages/vue/src/canvas/CanvasRoot.vue`	Composable de rendu du canevas
`packages/vue/src/canvas/useCanvasInput.ts`	Gestion des entrées souris/touch
`src/app/shell/keyboard/use.ts`	Gestion des raccourcis clavier

4.3 KiB Raw Blame History