refactor(annotation): use #src/* subpath imports for cross-directory refs

[contextbotai]

What & why

The root AGENTS.md Imports convention states:

Subpath imports for intra-package refs: every package declares "imports": { "#src/*": "./src/*" }. Code writes import { x } from '#src/context.ts'; for cross-directory imports. Same-directory siblings (e.g. plan.test.ts → ./plan.ts) may stay relative.

Every TypeScript workspace complies (cli, context, harness, instrumentation, server, shared, skills, storage, ui) except @contextbridge/annotation, which had neither the #src/* mapping nor a single subpath import. It reached across directory boundaries with relative ../ / ../../ paths — the exact pattern the convention forbids.

This was the single most-egregious violation class by frequency and clarity: 20 cross-directory relative imports across 10 files, all in one package, all mechanically fixable with zero behavior change.

Changes

• Added "imports": { "#src/*": "./src/*" } to packages/annotation/package.json, bringing it in line with every other source package.
• Converted all cross-directory ..//../../ imports to #src/* in:
  • src/demo/DemoStage.tsx
  • src/element/ElementAdapter.ts
  • src/element/mermaid/MermaidBlock.tsx
  • src/element/mermaid/mermaidAdapter.ts
  • src/element/mermaid/mermaidAdapter.test.ts
  • src/element/useElementTargets.ts
  • src/testHelpers/appContextDecorator.tsx
  • src/testHelpers/createFakeAppContext.ts
  • src/testHelpers/index.tsx
  • src/testHelpers/renderAnnotationHook.tsx

Same-directory ./ sibling imports were left relative, as the convention explicitly permits.

Verification

• bun run typecheck (annotation) — passes; TS moduleResolution: bundler resolves #src/* via the package.json imports field, no tsconfig paths needed.
• bun run build (annotation) — passes; Vite 6 resolves #src/* natively. Output is byte-identical to baseline (same 4840 modules transformed, same dist/index.html size), confirming no behavior change.
• prettier --check on all changed files — clean.
• eslint --max-warnings 0 on all changed files — clean (import ordering preserved).
• vitest (browser mode) collects all 12 test files without resolution errors. It could not launch the browser in this sandbox due to a pre-existing Playwright version mismatch (installed chromium-1228, @vitest/browser-playwright expects -1217) — an environment issue unrelated to this change; module resolution itself is confirmed working since collection succeeded.

Notes for the reviewer / future runs

Other, lower-priority violation classes I noticed but intentionally did not touch (one class per run):

• packages/instrumentation/src/node/harnessDiscovery.test.ts hand-rolls a local createDeferred (new Promise wrapper) instead of importing createDeferred from @contextbridge/shared/testHelpers, which the testing-patterns rule forbids. Single instance.
• A few readFileSync / readdirSync({ withFileTypes: true }) sites (skills/src/skills.ts, storage/src/db/loadMigrations.macro.ts, storage/src/paths.ts) could arguably move to Bun.file / Bun.Glob per the bun-native-apis rule, but that rule explicitly says the sync fs APIs are "not banned outright," so these are borderline.

The remaining ../ imports in packages/website are .astro/.mdx asset and component imports on Astro's own toolchain (not the TypeScript imports-field convention) and are out of scope.