my website at ewancroft.uk
chore: create READMEs for pkgs
+192
+83
packages/atproto/README.md
+83
packages/atproto/README.md
···
1
+
# @ewanc26/atproto
2
+
3
+
AT Protocol service layer extracted from [ewancroft.uk](https://ewancroft.uk). Handles identity resolution, record fetching, Bluesky posts, Standard.site documents, music/mood status, and more — with a built-in in-memory cache.
4
+
5
+
**Key difference from the app's internal service layer:** all functions accept `did: string` as their first argument rather than reading `PUBLIC_ATPROTO_DID` from the environment.
6
+
7
+
## Installation
8
+
9
+
```bash
10
+
pnpm add @ewanc26/atproto
11
+
```
12
+
13
+
Requires `@atproto/api >= 0.13.0` as a peer dependency.
14
+
15
+
## What's Exported
16
+
17
+
### Fetch Functions
18
+
19
+
| Function | Description |
20
+
|----------|-------------|
21
+
| `fetchProfile(did)` | Bluesky profile including pronouns |
22
+
| `fetchSiteInfo(did)` | `uk.ewancroft.site.info` record |
23
+
| `fetchLinks(did)` | `blue.linkat.board` link cards |
24
+
| `fetchMusicStatus(did)` | teal.fm music status with cascading artwork lookup |
25
+
| `fetchKibunStatus(did)` | kibun.social mood status |
26
+
| `fetchTangledRepos(did)` | Tangled code repositories |
27
+
| `fetchPublications(did)` | Standard.site publications |
28
+
| `fetchDocuments(did, pubRkey)` | Standard.site documents for a publication |
29
+
| `fetchBlogPosts(did, pubRkey)` | Blog posts for a publication |
30
+
| `fetchRecentDocuments(did, limit)` | Most recent documents across all publications |
31
+
| `fetchLatestBlueskyPost(did)` | Latest non-reply Bluesky post with thread context |
32
+
| `fetchPostFromUri(did, uri)` | Single Bluesky post by AT URI |
33
+
| `fetchAllEngagement(uris)` | Like/repost counts via Constellation API |
34
+
35
+
### Agents & Identity
36
+
37
+
```typescript
38
+
import { resolveIdentity, getPublicAgent, getPDSAgent, createAgent, withFallback, resetAgents } from '@ewanc26/atproto';
39
+
```
40
+
41
+
### Pagination
42
+
43
+
```typescript
44
+
import { fetchAllRecords, fetchAllUserRecords } from '@ewanc26/atproto';
45
+
```
46
+
47
+
### Cache
48
+
49
+
```typescript
50
+
import { cache, ATProtoCache, CACHE_TTL } from '@ewanc26/atproto';
51
+
52
+
cache.clear();
53
+
cache.delete('profile:did:plc:…');
54
+
```
55
+
56
+
### Music Artwork
57
+
58
+
```typescript
59
+
import { findArtwork, searchMusicBrainzRelease, buildCoverArtUrl } from '@ewanc26/atproto';
60
+
// Cascading: MusicBrainz → iTunes → Deezer → Last.fm → PDS blob
61
+
```
62
+
63
+
### Media
64
+
65
+
```typescript
66
+
import { buildPdsBlobUrl, extractCidFromImageObject, extractImageUrlsFromValue } from '@ewanc26/atproto';
67
+
```
68
+
69
+
### Types
70
+
71
+
All interfaces (`ProfileData`, `BlueskyPost`, `BlogPost`, `MusicStatusData`, `KibunStatusData`, `TangledRepo`, `StandardSiteDocument`, `StandardSitePublication`, `SiteInfoData`, `LinkData`, `ResolvedIdentity`, …) are exported from the package root.
72
+
73
+
## Build
74
+
75
+
```bash
76
+
pnpm build # tsc
77
+
pnpm dev # tsc --watch
78
+
pnpm check # tsc --noEmit
79
+
```
80
+
81
+
## Licence
82
+
83
+
See the root [LICENSE](../../LICENSE).
+65
packages/ui/README.md
+65
packages/ui/README.md
···
1
+
# @ewanc26/ui
2
+
3
+
Svelte UI component library extracted from [ewancroft.uk](https://ewancroft.uk). Provides layout and card components, UI primitives, SEO helpers, Svelte stores, post utilities, and a multi-theme configuration system.
4
+
5
+
## Installation
6
+
7
+
```bash
8
+
pnpm add @ewanc26/ui
9
+
```
10
+
11
+
Peer dependencies: `svelte >= 5`, `@sveltejs/kit >= 2`, `tailwindcss >= 4`. Optional: `@ewanc26/atproto` (for AT Protocol card components).
12
+
13
+
## What's Exported
14
+
15
+
### Components
16
+
17
+
| Group | Components |
18
+
|-------|------------|
19
+
| Layout toggles | `ThemeToggle`, `WolfToggle` |
20
+
| Layout main | `DynamicLinks`, `ScrollToTop` |
21
+
| Cards | `ProfileCard`, `PostCard`, `BlueskyPostCard`, `LinkCard`, `MusicStatusCard`, `KibunStatusCard`, `TangledRepoCard` |
22
+
| UI primitives | `Card`, `InternalCard`, `Dropdown`, `Pagination`, `SearchBar`, `Tabs`, `PostsGroupedView`, `DocumentCard`, `BlogPostCard` |
23
+
| SEO | `MetaTags` |
24
+
25
+
### Stores
26
+
27
+
| Store | Type | Description |
28
+
|-------|------|-------------|
29
+
| `wolfMode` | `Writable<boolean>` | Wolf mode text transformation |
30
+
| `colorTheme` | `Writable<ColorTheme>` | Active colour theme |
31
+
| `colorThemeDropdownOpen` | `Writable<boolean>` | Theme picker open state |
32
+
| `happyMacStore` | `Writable<boolean>` | Happy Mac easter egg |
33
+
34
+
### Theme Configuration
35
+
36
+
12 themes across four categories (neutral, warm, cool, vibrant) using OKLCH colour values. Default: `slate`.
37
+
38
+
```typescript
39
+
import { THEMES, DEFAULT_THEME, getTheme, getThemesByCategory, CATEGORY_LABELS } from '@ewanc26/ui';
40
+
```
41
+
42
+
### Helpers
43
+
44
+
```typescript
45
+
import { getPostBadges, getBadgeClasses } from '@ewanc26/ui';
46
+
import { filterPosts, groupPostsByDate, getSortedMonths, getSortedYears, getAllTags } from '@ewanc26/ui';
47
+
```
48
+
49
+
### Types
50
+
51
+
```typescript
52
+
import type { SiteMetadata, NavItem, ColorTheme, ThemeDefinition, PostBadge, MonthData, GroupedPosts } from '@ewanc26/ui';
53
+
```
54
+
55
+
## Build
56
+
57
+
```bash
58
+
pnpm build # svelte-package
59
+
pnpm dev # svelte-package --watch
60
+
pnpm check # svelte-check
61
+
```
62
+
63
+
## Licence
64
+
65
+
See the root [LICENSE](../../LICENSE).
+44
packages/utils/README.md
+44
packages/utils/README.md
···
1
+
# @ewanc26/utils
2
+
3
+
Shared utility functions extracted from [ewancroft.uk](https://ewancroft.uk). Zero runtime dependencies.
4
+
5
+
## Modules
6
+
7
+
- **Date & Locale** — `formatRelativeTime`, `formatLocalizedDate`, `getUserLocale`
8
+
- **Number Formatting** — `formatCompactNumber`, `formatNumber`
9
+
- **URL Utilities** — `getDomain`, `atUriToBlueskyUrl`, `getBlueskyProfileUrl`, `isExternalUrl`
10
+
- **Validators & Text** — `isValidTid`, `isValidDid`, `truncateText`, `escapeHtml`, `getInitials`, `debounce`, `throttle`
11
+
- **RSS Generation** — `generateRSSFeed`, `generateRSSItem`, `createRSSResponse`, `escapeXml`, `normalizeCharacters`, `formatRSSDate`
12
+
13
+
## Installation
14
+
15
+
```bash
16
+
pnpm add @ewanc26/utils
17
+
```
18
+
19
+
## Quick Examples
20
+
21
+
```typescript
22
+
import { formatRelativeTime, formatCompactNumber, getDomain, isValidDid, generateRSSFeed } from '@ewanc26/utils';
23
+
24
+
formatRelativeTime('2025-11-13T00:00:00Z'); // '3d ago'
25
+
formatCompactNumber(1500); // '1.5K'
26
+
getDomain('https://www.example.com/path'); // 'example.com'
27
+
isValidDid('did:plc:abc123'); // true
28
+
29
+
const xml = generateRSSFeed({ title: 'My Blog', link: 'https://mysite.com', description: '…' }, items);
30
+
```
31
+
32
+
All functions are SSR-safe and fall back to `en-GB` when `navigator` / `window` are unavailable.
33
+
34
+
## Build
35
+
36
+
```bash
37
+
pnpm build # tsc
38
+
pnpm dev # tsc --watch
39
+
pnpm check # tsc --noEmit
40
+
```
41
+
42
+
## Licence
43
+
44
+
See the root [LICENSE](../../LICENSE).