visionset 0.0.1b2__tar.gz

visionset-0.0.1b2/.agents/skills/backend/kernel-architecture/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: kernel-architecture
+description: >
+  VisionSet hexagonal architecture: what belongs in kernel/ vs server/, cli/, mcp/, formats/,
+  the machine-enforced import boundaries, and how to add a port, an adapter, or a format plugin.
+  Trigger: When adding or moving Python modules, designing domain models or ports, writing a
+  FastAPI route / Typer command / MCP tool, or when an import contract fails.
+license: Apache-2.0
+metadata:
+  author: robomous
+  version: "1.0"
+  scope: [root, backend]
+  auto_invoke:
+    - "Adding or moving modules under src/visionset/"
+    - "Writing a FastAPI route, Typer command, or MCP tool"
+    - "Fixing a lint-imports / architecture test failure"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## The shape
+
+```
+src/visionset/
+  kernel/     domain models + ports (Protocols) + default adapters — framework-free
+  server/     FastAPI. Thin: parse -> call SDK -> serialize
+  cli/        Typer. Thin: parse -> call SDK -> print
+  mcp/        MCP stdio server. Thin: tool -> SDK call
+  formats/    importer/exporter plugins, discovered via the `visionset.formats` entry point
+  _static/    compiled UI bundle, injected at build time
+```
+
+Every surface (UI, CLI, MCP, REST) is a **thin client of the same SDK**. If a behavior exists
+in only one of them, it is in the wrong place.
+
+## Two rules the machine enforces
+
+1. **Kernel purity** — `visionset.kernel` must never import `visionset.server`,
+   `visionset.cli`, `visionset.mcp`, `visionset.formats`, nor `fastapi` / `typer` / `mcp` /
+   `uvicorn`. Enforced by import-linter contracts in `pyproject.toml` **and** a fresh-process
+   test under `tests/architecture/`.
+2. **Delivery clients are siblings** — `server`, `cli`, and `mcp` never import each other.
+   Shared logic moves down into the kernel, never sideways.
+
+```bash
+uv run lint-imports        # both contracts
+uv run pytest tests/architecture
+```
+
+**If a change fights either boundary, the change is wrong — not the boundary.** Never relax a
+contract in `pyproject.toml` to make a build pass; restructure instead.
+
+## Where does this code go?
+
+| You are writing… | It goes in |
+| --- | --- |
+| A concept with invariants (Dataset, Annotation, Label) | `kernel/domain/` as a pydantic v2 model |
+| A use case / orchestration ("import a dataset") | `kernel/` service — callable from every surface |
+| An interface to the outside world (storage, repo, clock, ids) | `kernel/ports/` as a `Protocol` |
+| A concrete implementation of a port (filesystem, sqlite, uuid4) | `kernel/adapters/` |
+| HTTP shape: routes, request/response models, status codes | `server/` |
+| A `visionset ...` subcommand, flags, human output | `cli/` |
+| An MCP tool declaration and its mapping | `mcp/` |
+| Reading/writing COCO, YOLO, … | `formats/` + an entry point |
+
+Rule of thumb: **if it would still make sense with no HTTP, no terminal, and no LLM, it belongs
+in the kernel.**
+
+## Adding a port
+
+1. Define the `Protocol` in `kernel/ports/` — narrow, domain-worded (`ImageStore`, not
+   `S3Client`), fully typed, no framework types in the signature.
+2. Ship a default adapter in `kernel/adapters/` so local-first works with zero configuration.
+3. Inject it — constructor parameter with a default, never a module-level singleton and never
+   an import from a delivery module.
+4. Test against the Protocol with a fake; the default adapter gets its own test.
+
+## Adding a format plugin
+
+- Implement the importer/exporter under `formats/`.
+- Register it in `pyproject.toml` under `[project.entry-points."visionset.formats"]`.
+- Discovery goes through `importlib.metadata` — never a hardcoded registry, never an
+  `if fmt == "coco"` chain. Third-party distributions (`visionset-format-x`) register into the
+  same group; anything that breaks that breaks the plugin promise.
+- A change to the plugin surface ships with a test proving discoverability via
+  `importlib.metadata`.
+
+## Delivery-layer discipline
+
+- A route/command/tool body should read as: validate input → call one SDK function → shape the
+  output. Business logic in a route is a bug.
+- `openapi.json` at the repo root is a **committed contract** consumed by the generated TS
+  client. After changing routes or response models:
+  `uv run python scripts/export_openapi.py` and commit the diff.
+- Errors: raise domain errors from the kernel; translate them to HTTP status / exit codes at
+  the boundary. The kernel never raises `HTTPException`.

visionset-0.0.1b2/.agents/skills/backend/python-reviewer/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: python-reviewer
+description: >
+  Reviews and refines VisionSet Python (kernel, FastAPI, Typer, MCP, pydantic v2) for clarity,
+  consistency, and architectural fit while preserving behavior exactly. Focuses on recently
+  modified code unless told otherwise. Use proactively after Python changes.
+license: Apache-2.0
+metadata:
+  author: robomous
+  version: "1.0"
+  scope: [root, backend]
+  auto_invoke: "Reviewing or refactoring Python code"
+model: opus
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+You are an expert Python reviewer for a library-first, hexagonal codebase. Your job is to make
+recently modified code clearer, more consistent, and architecturally correct **without changing
+what it does**. You prefer explicit, readable code over clever compression.
+
+## 1. Preserve functionality
+
+Never change behavior — only how it is expressed. Same outputs, same errors, same side effects.
+Non-negotiable. If you believe behavior is wrong, report it separately; do not silently "fix" it
+inside a refactor.
+
+## 2. Enforce the architecture first
+
+Architecture violations outrank style. Check, in order:
+
+- Does anything in `visionset/kernel/` import `fastapi`, `typer`, `mcp`, `uvicorn`, or a
+  sibling delivery module? → must move.
+- Do `server`, `cli`, or `mcp` import each other? → the shared part moves down into the kernel.
+- Is there business logic inside a route handler, CLI command, or MCP tool? → it belongs in a
+  kernel service so every surface gets it.
+- Is a concrete dependency (filesystem, DB, clock, uuid) used directly instead of through a
+  port `Protocol`? → introduce/use the port.
+- Is a format handled by a hardcoded branch instead of the `visionset.formats` entry-point
+  group? → use discovery.
+
+See the `kernel-architecture` skill for where each kind of code belongs.
+
+## 3. Apply project standards
+
+- **ruff** owns formatting and import order (line length 100, rules `E, F, I, UP, B, SIM`).
+  Never introduce black/isort/flake8. Remove `# noqa` that hides a real fix.
+- Kernel code is fully typed under strict mypy: no untyped defs, no bare `Any`, no
+  `disallow_any_generics` escapes. Annotate new public functions outside the kernel too.
+- Naming: `snake_case` functions/variables, `PascalCase` classes, `UPPER_CASE` constants.
+  Name for the domain (`ImageStore`), not the technology (`S3Client`).
+- Imports at the top of the file; a function-local import needs a one-line reason.
+- f-strings over `%`/`format()`. `pathlib` over `os.path`. `enum.StrEnum` over string literals
+  scattered across modules.
+
+## 4. pydantic v2 and domain modelling
+
+- Invariants live in the model (`Field` constraints, `@field_validator`, `@model_validator`),
+  not re-checked at every call site.
+- Prefer `model_validate` / `model_dump` (v2 API); flag leftover v1 idioms (`parse_obj`,
+  `.dict()`, `class Config`, `@validator`).
+- Domain models are immutable where it costs nothing (`model_config = ConfigDict(frozen=True)`)
+  and never carry transport concerns (HTTP status, CLI flags, MCP schemas).
+- Value objects over primitive soup: an id type beats a bare `str` threaded through ten calls.
+
+## 5. Delivery layers
+
+**FastAPI (`server/`)**
+- Handlers stay thin: validate → one SDK call → shape response. Explicit `response_model` and
+  status codes.
+- Dependencies via `Depends`, not module-level globals.
+- Domain errors are translated to HTTP at the boundary; the kernel never raises
+  `HTTPException`.
+- Any route or response-model change requires re-exporting `openapi.json`
+  (`uv run python scripts/export_openapi.py`) — it is a committed contract.
+
+**Typer (`cli/`)**
+- One command = one SDK call plus presentation. Exit codes are meaningful.
+- Human-readable output by default; keep machine-readable output an explicit flag.
+
+**MCP (`mcp/`)**
+- A tool is a typed mapping onto an SDK function. Tool descriptions state what the tool does
+  and when to use it — they are the model's only documentation.
+
+## 6. Enhance clarity
+
+- Early returns over deep nesting; delete dead code and premature abstractions.
+- Remove comments that restate the code; keep comments that record *why* (a constraint, a
+  boundary, a decision).
+- Consolidate related logic; extract a well-named function instead of a comment-delimited block.
+- Narrow exception handling — no bare `except:`, no `except Exception` that swallows.
+- Prefer the stdlib over a new dependency; a new runtime dependency ships to every wheel user.
+
+## 7. Tests
+
+- New kernel behavior ships with tests under `tests/kernel/`; architecture rules under
+  `tests/architecture/`; plugin-surface changes prove discoverability via `importlib.metadata`.
+- Test behavior through public entry points, not private internals.
+- Ports are tested with fakes; each default adapter has its own test.
+- Never commit fixture media — `**/workspace-data/` stays ignored.
+
+## Output format
+
+Report as:
+
+1. **Architecture** — boundary violations (blocking).
+2. **Correctness risks** — behavior you suspect is wrong, stated as a question, not silently
+   changed.
+3. **Refinements applied** — file:line, one line each.
+4. **Checks run** — the actual commands and their result (`ruff`, `pytest`, `lint-imports`,
+   `mypy` when the kernel changed). Report failures verbatim; never claim green without running.

visionset-0.0.1b2/.agents/skills/backend/python-setup/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: python-setup
+description: >
+  Python environment and conventions for VisionSet. uv workspace, ruff (lint + format),
+  mypy (strict on the kernel), import-linter, pytest.
+  Trigger: When running Python scripts, formatting/linting Python code, adding dependencies,
+  or setting up the backend environment.
+license: Apache-2.0
+metadata:
+  author: robomous
+  version: "1.0"
+  scope: [root, backend]
+  auto_invoke: "Running Python scripts or setting up the Python environment"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## Environment
+
+- One Python distribution: `visionset`, living in `src/visionset/`. There is no `backend/`
+  folder and no `visionset_*` sibling packages.
+- Requires **Python 3.12+**. Package manager: **uv** (never pip, never poetry).
+- All commands run from the **repo root** — there is no per-component venv.
+
+```bash
+uv sync                      # create/refresh .venv with the package (editable) + dev group
+uv run python -c "..."       # run anything inside the env
+uv run pytest                # tests
+uv add <pkg>                 # runtime dependency  -> [project].dependencies
+uv add --dev <pkg>           # dev dependency      -> [dependency-groups].dev
+```
+
+Never edit `uv.lock` by hand; never `pip install` into `.venv`.
+
+## Checks that must stay green
+
+| Check | Command |
+| --- | --- |
+| Tests | `uv run pytest` |
+| Import contracts (architecture) | `uv run lint-imports` |
+| Kernel type-safety (strict) | `uv run mypy src/visionset/kernel` |
+| Lint | `uv run ruff check .` |
+| Format | `uv run ruff format .` |
+| OpenAPI contract | `uv run python scripts/export_openapi.py` (commit the diff) |
+
+Run at minimum `ruff check`, `ruff format`, `pytest`, and `lint-imports` after any Python
+change. If you touched the kernel, add `mypy`. If you touched FastAPI routes or response
+models, re-export `openapi.json` — it is a committed contract, a stale one is a bug.
+
+## Formatting and lint
+
+**ruff is both the formatter and the linter** — do not introduce black, isort, flake8, or
+autopep8. Line length is 100. Rule set: `E, F, I, UP, B, SIM` (configured in `pyproject.toml`;
+change it there, never with scattered `# noqa`).
+
+```bash
+uv run ruff format <path>    # format
+uv run ruff check --fix <path>
+```
+
+## Imports (REQUIRED)
+
+- Imports go at the top of the file. `ruff`'s `I` rules own the ordering — let the tool sort;
+  do not hand-order.
+- Import inside a function **only** to break a genuine cycle or to keep an optional dependency
+  optional, and say why in a one-line comment.
+- Nothing in `visionset.kernel` may import a framework or a delivery module — see the
+  `kernel-architecture` skill. That rule beats convenience, always.
+
+## Typing
+
+- The kernel is under strict mypy (`disallow_untyped_defs`, `disallow_any_generics`,
+  `warn_return_any`, …). Every kernel function is fully annotated; no bare `Any`.
+- Outside the kernel, follow the local style — annotate new public functions.
+- Domain invariants belong in the pydantic v2 models, not in ad-hoc `assert`s at call sites.
+
+## Versioning
+
+The repo-root `VERSION` file is the single source of truth. `pyproject.toml` reads it via
+hatchling's regex version source; `pnpm version:sync` propagates it to the npm packages.
+Never hand-edit a version anywhere else.
+
+## Dependency rules
+
+- A new runtime dependency in `[project].dependencies` ships to every user of the wheel —
+  justify it. The kernel must stay framework-free; tooling-only deps go to the dev group.
+- Importer/exporter plugins register under the `visionset.formats` entry-point group instead
+  of being imported directly.

visionset-0.0.1b2/.agents/skills/frontend/annotator-core/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: annotator-core
+description: >
+  The headless boundary of @visionset/annotator: pure-TS interaction state machine, geometry and
+  input in src/core/, React (and any other renderer) confined to src/adapters/.
+  Trigger: When adding or changing annotation behavior, canvas interaction, geometry, undo/redo,
+  or an annotator render adapter — and when the "no React in core" ESLint rule fires.
+license: Apache-2.0
+metadata:
+  author: robomous
+  version: "1.0"
+  scope: [frontend]
+  auto_invoke:
+    - "Changing annotation/canvas interaction behavior"
+    - "Adding or modifying an annotator render adapter"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## The shape
+
+```
+frontend/annotator/src/
+  core/           pure TypeScript — no React, no DOM globals
+    types.ts        the wire contract, mirrored exactly (annotations, schema, asset)
+    wire.ts         unknown in, typed out — plus the outbound create/update projections
+    ids.ts          the IdFactory port; core cannot mint a uuid, `crypto` is a host global
+    _fixture.ts     test harness (kernel-written fixture loader) — excluded from the build
+    geometry/       math: clamp, hit-testing, transforms
+    input/          normalized pointer/keyboard events -> intents
+    state/          document.ts + selection.ts + commandLog.ts (undo/redo)
+  adapters/
+    ids.ts          randomUuid — a host capability, not a renderer
+    react/          AnnotatorCanvas and friends — the only place React exists
+  index.ts        public entry point
+```
+
+**The document** (`state/document.ts`) is `AnnotationDocument`: an asset, a schema, and
+`ReadonlyMap<string, Annotation>`. Immutable — every operation returns a new one. Never named
+`Document` (a host global). Annotations are addressed by UUID, never by index.
+
+**Selection** (`state/selection.ts`) is a `ReadonlySet<string>` held *beside* the document and
+**filtered on read**, never pruned on write. That is what makes it survive undo/redo with no
+coordination: undoing a delete makes the annotation resolve again, still selected. Do not move
+selection into the document, and do not add an eager prune.
+
+The document refuses only its own invariants — duplicate id, unknown id, foreign asset. Kernel
+rules (class↔geometry agreement, required attributes, bounds) stay the kernel's; the tools refuse at
+draw time, where a user can be told.
+
+## The rules the machine enforces
+
+`src/core/**` must not import React and must not reach the DOM. Three gates, the frontend mirror
+of the backend's import-linter kernel contracts, all run by
+`pnpm --filter @visionset/annotator lint`:
+
+| Gate | Where | Scope | Catches |
+| --- | --- | --- | --- |
+| `no-restricted-imports` | `eslint.config.js` | `src/core/**` | `react`, `react-dom`, `react-*` |
+| `no-restricted-globals` | `eslint.config.js` | `src/core/**`, **tests included** | `document`, `window`, `navigator`, `requestAnimationFrame`, … as **values** |
+| `tsconfig.core.json` | its own file | `src/core/**` **minus** `*.test.ts` | DOM **types in signatures** (`KeyboardEvent`, `SVGSVGElement`), plus `setTimeout` / `console` / `fetch` in shipping code |
+
+Two ESLint rules and a compiler pass because each reaches where the others cannot. A lint rule
+reports *value* references, so `getSvgSize(svg: SVGSVGElement)` passes it — that is what the
+DOM-free `lib` is for. Conversely the type gate excludes the vitest harness, which legitimately
+runs under Node and reads a kernel-written fixture through `node:fs`; admitting it would take
+`types: ["node"]`, and @types/node re-declares `setTimeout`, `console` and `fetch`, so buying the
+tests would cost the timer ban on the engine. The ESLint half covers those files instead.
+
+`tests/scripts/annotator_boundary.test.mjs` proves all three fire, and pins the two traps: `jsx:
+"preserve"` in `tsconfig.core.json` is load-bearing (`jsx: "react-jsx"` imports
+`react/jsx-runtime`'s types into every file, dragging in @types/react's empty `interface
+KeyboardEvent {}` DOM stand-ins), and a type-gate probe must live inside the package, because from
+`os.tmpdir()` nothing resolves `node_modules` and the probe fails for the wrong reason.
+
+**If a change fights the boundary, the change is wrong — not the boundary.** Do not add an
+eslint-disable, do not widen a rule's file scope, do not put `DOM` back in the `lib`.
+
+When a gate fires, the fix is one of:
+
+- The logic is renderer-agnostic → keep it in `core/`, drop the React import or the DOM reference
+  (take values as arguments, return plain data).
+- The logic is genuinely about rendering → move it to `adapters/react/`.
+- The signature wanted a DOM type for its *shape* → define the shape in `core/` as a plain
+  interface. That is what the input layer's normalized events are for; a DOM type in a core
+  signature is the leak this gate exists to stop.
+
+## Writing core logic
+
+- Pure functions and explicit state transitions. No hidden globals, no `window`/`document`
+  access, no timers owned by core — the adapter supplies those.
+- Input arrives as normalized events; core returns intents/state, never DOM mutations.
+- Every mutating action goes through the command log so undo/redo stays a core capability, not
+  an adapter feature.
+- Deterministic: same input sequence → same state. That is what makes it testable and what will
+  let 3D/point-cloud modes reuse it later.
+
+## Writing an adapter
+
+An adapter only: subscribes to core state, paints it, and forwards normalized input back. It
+holds no annotation logic of its own. React is the first adapter, not the only intended one —
+anything it "knows" that core doesn't will not survive the second renderer.
+
+## Tests
+
+Core is unit-tested with **vitest** and needs no DOM:
+
+```bash
+pnpm --filter @visionset/annotator test
+pnpm --filter @visionset/annotator lint   # all three headless boundary gates
+```
+
+The wire mirror is proved against `tests/fixtures/wire_annotations.json`, which
+`scripts/export_wire_fixtures.py` writes from the same pydantic models `openapi.json` comes from —
+it carries the asset, the schema and the annotations a document is built from. Never hand-write a
+TypeScript copy of a kernel shape: extend the exporter and regenerate
+(`uv run python scripts/export_wire_fixtures.py`), which both gates then hold in step.
+
+`lint` is `eslint src` plus two compiler passes — `typecheck` (the whole package, tests included)
+and `typecheck:core` (the boundary). Either is runnable on its own by name.
+
+New interaction behavior ships with a core test that drives the state machine directly.

visionset-0.0.1b2/.agents/skills/frontend/nodejs-setup/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: nodejs-setup
+description: >
+  Frontend environment for the VisionSet pnpm workspace. Node.js 24, corepack/pnpm, per-package
+  and recursive scripts.
+  Trigger: When setting up the frontend environment, installing packages, adding a workspace
+  package, or running frontend build/test/lint scripts.
+license: Apache-2.0
+metadata:
+  author: robomous
+  version: "1.0"
+  scope: [frontend]
+  auto_invoke: "Setting up frontend environment or installing packages"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## Environment
+
+- **Node.js 24**. With nvm on the host: `nvm use 24`.
+- **pnpm** only (never npm, never yarn). Pinned via `packageManager` in the root
+  `package.json` — enable it with `corepack enable`.
+- Single **pnpm workspace** rooted at the repo root; members are `frontend/*`
+  (`@visionset/annotator`, `@visionset/ui-core`, `@visionset/app`).
+- Run commands **from the repo root**.
+
+## Commands
+
+```bash
+pnpm install                     # install the whole workspace
+
+pnpm -r build                    # build every package (topological order)
+pnpm -r test                     # vitest where defined
+pnpm -r lint                     # eslint
+
+pnpm --filter @visionset/app dev            # Vite dev server
+pnpm --filter @visionset/annotator test     # one package
+pnpm --filter @visionset/ui-core build
+
+pnpm version:sync                # propagate repo-root VERSION into frontend/*/package.json
+pnpm bundle:static               # place the built app into src/visionset/_static/
+```
+
+## Dependencies
+
+```bash
+pnpm --filter @visionset/app add <pkg>          # runtime dep of one package
+pnpm --filter @visionset/ui-core add -D <pkg>   # dev dep of one package
+pnpm add -w -D <pkg>                            # root tooling only
+```
+
+- Cross-package references use the workspace protocol: `"@visionset/annotator": "workspace:*"`.
+- `@visionset/annotator` keeps `react` as an **optional peer dependency** — never promote it to
+  a hard dependency; the core must stay usable without React.
+- `@visionset/ui-core` UI primitives are **Radix + lucide only**. Do not add another component
+  library.
+- `@visionset/app` is `private: true` — never published to npm; its bundle ships inside the
+  Python wheel.
+
+## Versions
+
+Never hand-edit a `version` field. The repo-root `VERSION` file is the source of truth;
+`pnpm version:sync` converts it to npm semver (`0.1.0.dev0` → `0.1.0-dev.0`).
+
+## Before you say it works
+
+`pnpm -r build && pnpm -r test && pnpm -r lint` from the root. Report failures verbatim.

visionset-0.0.1b2/.agents/skills/frontend/react-19/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: react-19
+description: >
+  React 19 patterns with React Compiler.
+  Trigger: When writing React 19 components/hooks in .tsx (React Compiler rules, hook patterns,
+  refs as props).
+license: Apache-2.0
+metadata:
+  author: robomous
+  version: "1.0"
+  scope: [root, frontend]
+  auto_invoke: "Writing React components"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## Where React is allowed (VisionSet)
+
+| Package | React? |
+| --- | --- |
+| `frontend/annotator/src/core/` | **Never** — pure TS, ESLint-enforced |
+| `frontend/annotator/src/adapters/react/` | Yes — the render adapter |
+| `frontend/ui-core/` | Yes — domain components (Radix + lucide only) |
+| `frontend/app/` | Yes — the product shell |
+
+## No Manual Memoization (REQUIRED)
+
+```typescript
+// ✅ React Compiler handles optimization automatically
+function Component({ items }) {
+  const filtered = items.filter(x => x.active);
+  const sorted = filtered.sort((a, b) => a.name.localeCompare(b.name));
+
+  const handleClick = (id) => {
+    console.log(id);
+  };
+
+  return <List items={sorted} onClick={handleClick} />;
+}
+
+// ❌ NEVER: Manual memoization
+const filtered = useMemo(() => items.filter((x) => x.active), [items]);
+const handleClick = useCallback((id) => console.log(id), []);
+```
+
+## Imports (REQUIRED)
+
+```typescript
+// ✅ ALWAYS: Named imports
+import { useState, useEffect, useRef } from "react";
+
+// ❌ NEVER
+import React from "react";
+import * as React from "react";
+```
+
+## use() Hook
+
+```typescript
+import { use } from "react";
+
+// Read promises (suspends until resolved)
+function Comments({ promise }) {
+  const comments = use(promise);
+  return comments.map(c => <div key={c.id}>{c.text}</div>);
+}
+
+// Conditional context (not possible with useContext!)
+function Theme({ showTheme }) {
+  if (showTheme) {
+    const theme = use(ThemeContext);
+    return <div style={{ color: theme.primary }}>Themed</div>;
+  }
+  return <div>Plain</div>;
+}
+```
+
+## ref as Prop (No forwardRef)
+
+```typescript
+// ✅ React 19: ref is just a prop
+function Input({ ref, ...props }) {
+  return <input ref={ref} {...props} />;
+}
+
+// ❌ Old way (unnecessary now)
+const Input = forwardRef((props, ref) => <input ref={ref} {...props} />);
+```
+
+## Keep components thin
+
+Annotation behavior (hit-testing, geometry, undo/redo, interaction state) belongs in
+`@visionset/annotator` core, not in a component. A React component subscribes to core state and
+renders it. If deleting React would delete the logic, the logic is in the wrong package.