docs: rewrite README with namespace examples and better quick start

[Kadajett]

Summary

• Rewrites the Quick Start example to use factory functions (createScreenEntity, createBoxEntity, etc.) instead of raw SoA component access
• Adds new "Namespace Imports" section showing position, scroll, content, rope, colors namespace usage
• Adds Import Tiers table explaining the three-tier export system
• Adds "Addon Packages" section with namespace and subpath import examples for @blecsd/3d, @blecsd/ai, @blecsd/media
• Updates Components table with namespace column
• Updates Library Design code to use namespace imports

Closes #1250

Test plan

• Verify all import paths in code examples are valid
• Verify namespace property references match actual exports
• Visual review of README rendering on GitHub

[github-actions]

Performance Check Results

📁 Results file: benchmark-results.json
📏 Threshold: 20%

✅ Loaded baseline from: 2026-02-08T18:50:00.000Z

/home/runner/work/blECSd/blECSd/scripts/check-perf-regression.ts:67
		throw new Error(`Results file not found: ${resultsPath}`);
		      ^

Error: Results file not found: benchmark-results.json
    at parseResults (/home/runner/work/blECSd/blECSd/scripts/check-perf-regression.ts:67:9)
    at main (/home/runner/work/blECSd/blECSd/scripts/check-perf-regression.ts:225:25)
    at <anonymous> (/home/runner/work/blECSd/blECSd/scripts/check-perf-regression.ts:235:1)
    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:665:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5)

Node.js v22.22.0

[Copilot]

Pull request overview

This PR rewrites the README.md to showcase blECSd's namespace-based API and provide better quick start examples. It addresses issue #1250 by replacing low-level SoA component access examples with higher-level factory functions and namespace objects, making the library more approachable for new users.

Changes:

• Replaces Quick Start with a complete terminal app example using factory functions (createScreenEntity, createBoxEntity, etc.)
• Adds comprehensive "Namespace Imports" section demonstrating the position, scroll, content, rope, colors namespace pattern
• Adds Import Tiers table explaining the three-tier export system (Tier 1: curated essentials, Tier 2: full module access, Tier 3: deep imports)
• Documents addon packages (@blecsd/3d, @blecsd/ai, @blecsd/audio, @blecsd/game, @blecsd/media) with namespace and subpath import examples
• Updates Components table to include namespace column for discoverability
• Updates Library Design code examples to use namespace imports

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The method name should be colors.colorToHex instead of colors.rgbToHex. The colors namespace does not have an rgbToHex method - it exports colorToHex, hexToColor, packColor, unpackColor, and parseColor.

Suggested change

	const hex = colors.rgbToHex(255, 100, 0);
	const hex = colors.colorToHex(255, 100, 0);

[Copilot]

The method list.select does not exist. To select an item at a specific index, use list.selection.setIndex(world, eid, 2) instead. The list namespace organizes selection methods under the selection sub-namespace.

Suggested change

	list.select(world, eid, 2); // select item at index
	list.selection.setIndex(world, eid, 2); // select item at index

[Copilot]

The conversation.addMessage function signature is incorrect. According to the implementation, addMessage takes (state: ConversationState, role: MessageRole, content: string, id?: string) as parameters, not an object. The correct call should be: conversation.addMessage(state, 'user', 'Hello');

Suggested change

	conversation.addMessage(state, { role: 'user', content: 'Hello' });
	conversation.addMessage(state, 'user', 'Hello');

[Copilot]

The projection.perspective function takes a configuration object, not individual parameters. The correct call should be: projection.perspective({ fov: 60, aspect: 1.5, near: 0.1, far: 100 }) instead of projection.perspective(60, 1.5, 0.1, 100).

Suggested change

	const mvp = mat4.multiply(projection.perspective(60, 1.5, 0.1, 100), viewMatrix);
	const mvp = mat4.multiply(
	projection.perspective({ fov: 60, aspect: 1.5, near: 0.1, far: 100 }),
	viewMatrix
	);

[Copilot]

The method name should be rope.createRope instead of rope.create. The rope namespace does not have a create method - it exports createRope and createEmptyRope.

Suggested change

	const r = rope.create('Hello');
	const r = rope.createRope('Hello');