core-sdk: Instructions file for Codex

AGENTS.md

Purpose

This file defines the default working rules for AI coding agents operating in the Flowscape repository.

Flowscape is a developer-first, framework-agnostic 2D engine for building infinite-canvas editors, design tools, visual builders, whiteboards, diagram editors, and similar graphical applications.

Treat Flowscape as an engine, not as an application framework or a collection of UI components. Preserve the separation between scene state, node state, rendering, input, hosts, and application-level code.

These rules apply to the entire repository unless a more specific AGENTS.md exists deeper in the directory tree.

---

Repository Layout

Flowscape is a Bun + Turborepo monorepo.

flowscape/
├── apps/
│   ├── docs/
│   └── playground/
├── packages/
│   └── engine/
├── package.json
├── turbo.json
└── bun.lock

Primary ownership:

• packages/engine - the Flowscape engine, published as @flowscape-ui/core-sdk.
• apps/playground - the development and manual-testing application.
• apps/docs - the Docusaurus documentation site.
• root - monorepo orchestration and shared tooling only.

Add dependencies to the workspace that actually uses them. Do not place package-specific runtime dependencies in the root package.

---

Project Identity and Architectural Direction

Flowscape is a low-level scene engine. It should provide reusable foundations for editor-like products without becoming coupled to a specific UI framework or product implementation.

Core principles:

1. Keep engine state independent from rendering-backend objects whenever practical.
2. Keep rendering logic out of node/model classes.
3. Keep input/controller logic separate from renderers.
4. Keep application-specific behavior out of the engine unless it is a reusable editor primitive.
5. Prefer stable, extensible public APIs over shortcuts that expose implementation details.
6. Preserve the ability to evolve rendering backends without rewriting product logic.
7. Do not introduce abstractions only because they look cleaner; introduce them when they solve a real ownership, reuse, performance, or extensibility problem.