@atmo-dev/kit 0.2.1 → 0.3.0

package/README.md

@@ -9,6 +9,47 @@ Svelte 5 and Tailwind CSS 4 components for Atmo apps.
 - Releases: `pnpm changeset`, then merge the generated release PR. [Details](.changeset/README.md).
 - License: [MIT](LICENSE).
 
+## Read-only profiles
+
+`UserProfile` displays a Bluesky profile header: banner, avatar, name, handle, pronouns, optional counts, bio, modern profile links, and a DID-based “View on Bluesky” link. It has no editing or follow behavior. An optional `actions` snippet holds app-owned controls. `metrics={[{ label: 'events created', value: 12 }]}` replaces the default Bluesky counts; `metrics={[]}` hides all counts.
+
+```svelte
+<script lang="ts">
+	import { UserProfile, blueskyProfileToProfileData } from '@atmo-dev/kit';
+
+	// Fetch and apply moderation in the app, not in the component.
+	let { profileView } = $props();
+	let profile = $derived(blueskyProfileToProfileData(profileView));
+</script>
+
+{#if profile}<UserProfile {profile} />{/if}
+```
+
+`ProfileData` can also be supplied directly. Bios remain escaped plain text with detected HTTP(S) links, mentions and hashtags; newlines are preserved. There is no HTML/Markdown interpretation, DOM sanitizer, client-only rendering, or mention-resolution request. Link destinations and images reject executable schemes and credential-bearing URLs. External links use `noopener noreferrer`; user links also use `nofollow ugc`.
+
+`blueskyProfileToProfileData` accepts an `app.bsky.actor.getProfile` view and validates optional fields. Its `links` must be hydrated `app.bsky.actor.link` views (`url`, optional `title` and `icon` image URL), not the profile record's ordered strongRefs. It omits unresolved refs and labeled links conservatively, deduplicates destinations, and displays at most ten. The legacy `website` field is deliberately ignored. Apps own hydration, account moderation and any more specific link-moderation policy. Supplied icons render as small decorative images; unsafe or failed icons fall back to text-only links. No link metadata or destination is fetched by the component.
+
+## Preferred social client
+
+`SocialClientPicker` is a native form field group for Bluesky, mu, Blacksky, Witchsky, or a custom web client. Pass the viewer's saved `value` (a `PreferredSocialClient`, or `null` for Bluesky) and optionally `disabled`. It submits `client` and, for custom clients, `customUrl`. The app owns the form, save button, authentication, and feedback.
+
+The dedicated public record is `social.atmo.actor.preferredClient/self`:
+
+```json
+{ "$type": "social.atmo.actor.preferredClient", "client": "mu" }
+```
+
+For a custom client, use `"client": "custom"` and `"customUrl": "https://example.com"`. This lexicon stores **only social-client selection**, not general preferences. Its schema is available at `@atmo-dev/kit/lexicons/social.atmo.actor.preferredClient.json`.
+
+Framework-free helpers are exported from `@atmo-dev/kit/social` (and the main entry point):
+
+- `PREFERRED_CLIENT_COLLECTION`, `PREFERRED_CLIENT_RKEY`, `PREFERRED_CLIENT_SCOPE` for repository IO and OAuth metadata/incremental permission requests. The scope grants create/update only on this collection; request it when the user chooses to authorize this setting, not during normal login or signup.
+- `parsePreferredSocialClient(record)` validates repository records or form input; invalid, unknown or absent selections return `null`.
+- `preferredSocialClientRecord(selection)` builds a validated record. Never write merely because a read failed; distinguish `RecordNotFound` from PDS/network failures, and use `swapRecord` to guard updates.
+- `socialClientInfo(selection)`, `socialProfileUrl(actor, selection)`, `socialPostUrl(atUri, selection)`, and `socialHashtagUrl(tag, selection)` default to Bluesky. `socialPostUrl` accepts feed-post AT URIs and returns `null` for invalid ones. Custom URLs must be absolute HTTP(S), without credentials, query or fragment, and support `/profile/:actor` routes. Base paths are preserved.
+
+Read the signed-in viewer's record from their PDS, include the parsed selection in viewer data, and pass it to `<UserProfile {profile} socialClient={viewer.preferredSocialClient} />`. The profile's external button and handle link use that client. Pass the same `socialClient` prop to `NestedComments` for author, reply and like links, including nested replies. Changing the selection updates these links without changing the stored post data. Bio hashtags also use the selected client. Supply an app-owned `mentionUrl` callback to `UserProfile` (for example, `(actor) => '/p/' + encodeURIComponent(actor)`) to route bio mentions locally in the same tab; without it they open the selected social client. Post-content facets retain their existing Bluesky links. Apps remain responsible for server-side authorization, IO, incremental authorization when access is missing, and invalidating viewer data after saves.
+
 ## Login identifiers
 
 `LoginForm` and `LoginDialog` accept handles and DIDs by default. Handles are trimmed, stripped of leading `@` characters, and lowercased. DIDs are trimmed only: method-specific case and percent encoding are preserved. `initialHandle` also accepts a DID; its existing name is retained for compatibility.

package/dist/components/NestedComments.svelte

@@ -1,19 +1,27 @@
 <script lang="ts">
 	import type { PostData } from '../social/posts.js';
 	import { safeWebUrl } from '../social/richtext.js';
-	import { blueskyProfileUrl } from '../social/urls.js';
+	import { socialPostUrl, socialProfileUrl } from '../social/urls.js';
+	import type { PreferredSocialClient } from '../social/preferred-client.js';
 	import Avatar from './Avatar.svelte';
 	import PostContent from './PostContent.svelte';
 	import NestedComments from './NestedComments.svelte';
-	let { comments }: { comments: PostData[] } = $props();
+	let {
+		comments,
+		socialClient
+	}: {
+		comments: PostData[];
+		socialClient?: PreferredSocialClient | null;
+	} = $props();
 </script>
 
 <div class="space-y-6" data-slot="comments">
 	{#each comments as comment (comment.uri)}
+		{@const href = socialPostUrl(comment.uri, socialClient) ?? safeWebUrl(comment.href)}
 		<article class="min-w-0">
 			<div class="flex items-start gap-3">
 				<a
-					href={blueskyProfileUrl(comment.author.did)}
+					href={socialProfileUrl(comment.author.did, socialClient)}
 					target="_blank"
 					rel="noopener noreferrer"
 					class="shrink-0"
@@ -22,7 +30,7 @@
 				<div class="min-w-0 flex-1">
 					<div class="mb-1 flex flex-wrap items-baseline gap-x-2 text-xs">
 						<a
-							href={safeWebUrl(comment.href)}
+							{href}
 							target="_blank"
 							rel="noopener noreferrer"
 							class="font-medium text-ink hover:underline">{comment.author.name}</a
@@ -38,24 +46,17 @@
 					</div>
 					<PostContent post={comment} />
 					<div class="mt-2 flex gap-5 text-[.6875rem] text-muted">
-						<a
-							href={safeWebUrl(comment.href)}
-							target="_blank"
-							rel="noopener noreferrer"
-							class="hover:text-action"
+						<a {href} target="_blank" rel="noopener noreferrer" class="hover:text-action"
 							>Reply{#if comment.replyCount}
 								· {comment.replyCount}{/if}</a
-						><a
-							href={safeWebUrl(comment.href)}
-							target="_blank"
-							rel="noopener noreferrer"
-							class="hover:text-action">{comment.likeCount ?? 0} likes</a
+						><a {href} target="_blank" rel="noopener noreferrer" class="hover:text-action"
+							>{comment.likeCount ?? 0} likes</a
 						>
 					</div>
 				</div>
 			</div>
 			{#if comment.replies?.length}<div class="mt-4 border-l border-line pl-3 sm:ml-4 sm:pl-6">
-					<NestedComments comments={comment.replies} />
+					<NestedComments comments={comment.replies} {socialClient} />
 				</div>{/if}
 		</article>
 	{/each}

package/dist/components/NestedComments.svelte.d.ts

@@ -1,7 +1,9 @@
 import type { PostData } from '../social/posts.js';
+import type { PreferredSocialClient } from '../social/preferred-client.js';
 import NestedComments from './NestedComments.svelte';
 type $$ComponentProps = {
     comments: PostData[];
+    socialClient?: PreferredSocialClient | null;
 };
 declare const NestedComments: import("svelte").Component<$$ComponentProps, {}, "">;
 type NestedComments = ReturnType<typeof NestedComments>;

package/dist/components/SocialClientPicker.svelte

@@ -0,0 +1,50 @@
+<script lang="ts" module>
+	import type { PreferredSocialClient } from '../social/preferred-client.js';
+	export type SocialClientPickerProps = {
+		value?: PreferredSocialClient | null;
+		disabled?: boolean;
+	};
+</script>
+
+<script lang="ts">
+	import { socialClients } from '../social/preferred-client.js';
+	import Select from './Select.svelte';
+	import Input from './Input.svelte';
+	import Label from './Label.svelte';
+
+	let { value = null, disabled = false }: SocialClientPickerProps = $props();
+	const id = $props.id();
+	let client: string = $derived(value?.client ?? 'bluesky');
+	let customUrl = $derived(value?.client === 'custom' ? value.customUrl : '');
+</script>
+
+<div class="grid gap-4">
+	<div class="grid gap-2">
+		<Label for={`${id}-client`}>Preferred social app</Label>
+		<Select id={`${id}-client`} name="client" bind:value={client} {disabled}>
+			{#each socialClients as option (option.id)}
+				<option value={option.id}>{option.label}</option>
+			{/each}
+			<option value="custom">Custom</option>
+		</Select>
+	</div>
+	{#if client === 'custom'}
+		<div class="grid gap-2">
+			<Label for={`${id}-url`}>Client URL</Label>
+			<Input
+				id={`${id}-url`}
+				name="customUrl"
+				type="url"
+				bind:value={customUrl}
+				{disabled}
+				required
+				maxlength={2048}
+				placeholder="https://your-client.example"
+				aria-describedby={`${id}-hint`}
+			/>
+			<p id={`${id}-hint`} class="text-sm text-muted">
+				Use a web client with Bluesky-style profile links.
+			</p>
+		</div>
+	{/if}
+</div>

package/dist/components/SocialClientPicker.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { PreferredSocialClient } from '../social/preferred-client.js';
+export type SocialClientPickerProps = {
+    value?: PreferredSocialClient | null;
+    disabled?: boolean;
+};
+declare const SocialClientPicker: import("svelte").Component<SocialClientPickerProps, {}, "">;
+type SocialClientPicker = ReturnType<typeof SocialClientPicker>;
+export default SocialClientPicker;

package/dist/components/UserProfile.svelte

@@ -0,0 +1,151 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { cn } from '../utils.js';
+	import {
+		profileDescriptionSegments,
+		safeProfileUrl,
+		visibleProfileLinks,
+		type ProfileData
+	} from '../social/profile.js';
+	import { socialProfileUrl } from '../social/urls.js';
+	import { socialClientInfo, type PreferredSocialClient } from '../social/preferred-client.js';
+	import Avatar from './Avatar.svelte';
+	import Button from './Button.svelte';
+
+	export type UserProfileProps = {
+		profile: ProfileData;
+		/** The viewer's choice, not the profile owner's. Defaults to Bluesky. */
+		socialClient?: PreferredSocialClient | null;
+		/** Route bio mentions to an app-owned profile instead of the social client. */
+		mentionUrl?: (identifier: string) => string;
+		actions?: Snippet;
+		/** App-owned metrics replace the default Bluesky counts, including an empty array. */
+		metrics?: { label: string; value: number }[];
+		class?: string;
+	};
+	let {
+		profile,
+		socialClient,
+		mentionUrl,
+		actions,
+		metrics,
+		class: className
+	}: UserProfileProps = $props();
+	let displayedMetrics = $derived(
+		metrics ??
+			[
+				{ value: profile.followersCount, label: 'followers' },
+				{ value: profile.followsCount, label: 'following' },
+				{ value: profile.postsCount, label: 'posts' }
+			].filter((metric) => metric.value !== undefined)
+	);
+	let name = $derived(profile.displayName || profile.handle || profile.did);
+	let href = $derived(socialProfileUrl(profile.did, socialClient));
+	let clientLabel = $derived(socialClientInfo(socialClient).label);
+	let failedBanner = $state<string>();
+	let bannerSrc = $derived(safeProfileUrl(profile.banner));
+	let banner = $derived(bannerSrc !== failedBanner ? bannerSrc : undefined);
+	let links = $derived(visibleProfileLinks(profile.links));
+	let failedLinkIcons = $state<Record<string, string>>({});
+	let pronouns = $derived(profile.pronouns?.trim().toLowerCase());
+</script>
+
+<section class={cn('min-w-0 text-ink', className)} aria-label="Profile">
+	{#if banner}
+		<div
+			data-slot="profile-banner"
+			class="relative aspect-3/1 w-full overflow-hidden rounded-panel bg-recess"
+		>
+			<img
+				src={banner}
+				alt=""
+				width="1500"
+				height="500"
+				class="absolute inset-0 size-full object-cover"
+				loading="eager"
+				fetchpriority="high"
+				decoding="async"
+				referrerpolicy="no-referrer"
+				onerror={(event) => (failedBanner = event.currentTarget.getAttribute('src') ?? undefined)}
+			/>
+		</div>
+	{/if}
+	<div class={cn('flex flex-wrap items-start justify-between gap-4', banner ? 'px-4' : '')}>
+		<Avatar
+			{name}
+			src={safeProfileUrl(profile.avatar)}
+			size={96}
+			class={cn('relative size-20 sm:size-24', banner && '-mt-10 ring-4 ring-page sm:-mt-12')}
+		/>
+		<div class={cn('flex flex-wrap items-center gap-2', banner && 'pt-3')}>
+			<Button {href} target="_blank" rel="noopener noreferrer" variant="secondary" size="sm">
+				View on {clientLabel}
+			</Button>
+			{@render actions?.()}
+		</div>
+	</div>
+	<div class="mt-4 min-w-0">
+		<h1 class="text-2xl font-semibold tracking-tight wrap-anywhere sm:text-3xl">
+			<bdi>{name}</bdi>
+		</h1>
+		<div class="mt-1 flex flex-wrap items-baseline gap-x-3 gap-y-1 text-sm text-muted">
+			{#if profile.handle}<a
+					{href}
+					target="_blank"
+					rel="noopener noreferrer"
+					class="min-w-0 wrap-anywhere hover:underline"><bdi>@{profile.handle}</bdi></a
+				>{/if}
+			{#if pronouns}<span aria-label="Pronouns"><bdi>{pronouns}</bdi></span>{/if}
+		</div>
+	</div>
+	{#if displayedMetrics.length}
+		<dl aria-label="Profile statistics" class="mt-4 flex flex-wrap gap-x-4 gap-y-1 text-sm">
+			{#each displayedMetrics as metric (metric.label)}
+				{#if metric.value !== undefined}<div class="flex gap-1">
+						<dd class="font-semibold">{metric.value.toLocaleString('en')}</dd>
+						<dt class="text-muted">{metric.label}</dt>
+					</div>{/if}
+			{/each}
+		</dl>
+	{/if}
+	{#if profile.description}
+		<p class="mt-4 text-sm leading-relaxed wrap-anywhere whitespace-pre-wrap">
+			{#each profileDescriptionSegments( profile.description, { socialClient, mentionUrl } ) as segment, index (index)}{#if segment.href}<a
+						href={segment.href}
+						target={segment.href.startsWith('/') ? undefined : '_blank'}
+						rel={segment.href.startsWith('/') ? undefined : 'noopener noreferrer nofollow ugc'}
+						class="text-action underline decoration-action/40 underline-offset-2 hover:decoration-action"
+						>{segment.text}</a
+					>{:else}{segment.text}{/if}{/each}
+		</p>
+	{/if}
+	{#if links.length}
+		<ul aria-label="Profile links" class="mt-4 flex flex-wrap gap-2">
+			{#each links as link (link.url)}
+				<li class="max-w-full min-w-0">
+					<a
+						href={link.url}
+						target="_blank"
+						rel="noopener noreferrer nofollow ugc"
+						class="inline-flex max-w-full items-center gap-2 rounded-ui border border-line px-3 py-1.5 text-sm hover:bg-recess"
+					>
+						{#if link.icon && failedLinkIcons[link.url] !== link.icon}
+							<img
+								src={link.icon}
+								alt=""
+								width="16"
+								height="16"
+								class="size-4 shrink-0 rounded-sm object-contain"
+								loading="lazy"
+								decoding="async"
+								referrerpolicy="no-referrer"
+								onerror={() => (failedLinkIcons[link.url] = link.icon ?? '')}
+							/>
+						{/if}
+						<span class="min-w-0 wrap-anywhere">{link.title || new URL(link.url).hostname}</span>
+					</a>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+</section>

package/dist/components/UserProfile.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+import { type ProfileData } from '../social/profile.js';
+import { type PreferredSocialClient } from '../social/preferred-client.js';
+export type UserProfileProps = {
+    profile: ProfileData;
+    /** The viewer's choice, not the profile owner's. Defaults to Bluesky. */
+    socialClient?: PreferredSocialClient | null;
+    /** Route bio mentions to an app-owned profile instead of the social client. */
+    mentionUrl?: (identifier: string) => string;
+    actions?: Snippet;
+    /** App-owned metrics replace the default Bluesky counts, including an empty array. */
+    metrics?: {
+        label: string;
+        value: number;
+    }[];
+    class?: string;
+};
+declare const UserProfile: import("svelte").Component<UserProfileProps, {}, "">;
+type UserProfile = ReturnType<typeof UserProfile>;
+export default UserProfile;

package/dist/index.d.ts

@@ -5,6 +5,9 @@ export { default as Input } from './components/Input.svelte';
 export type { InputProps } from './components/Input.svelte';
 export { default as Textarea } from './components/Textarea.svelte';
 export { default as Select } from './components/Select.svelte';
+export { default as SocialClientPicker } from './components/SocialClientPicker.svelte';
+export type { SocialClientPickerProps } from './components/SocialClientPicker.svelte';
+export * from './social.js';
 export { default as Checkbox } from './components/Checkbox.svelte';
 export { default as Label } from './components/Label.svelte';
 export { default as PageTitle } from './components/PageTitle.svelte';
@@ -12,6 +15,10 @@ export { default as Heading } from './components/Heading.svelte';
 export { default as Subheading } from './components/Subheading.svelte';
 export { default as Surface } from './components/Surface.svelte';
 export { default as Avatar } from './components/Avatar.svelte';
+export { default as UserProfile } from './components/UserProfile.svelte';
+export type { UserProfileProps } from './components/UserProfile.svelte';
+export { blueskyProfileToProfileData } from './social/profile.js';
+export type { ProfileData, ProfileLink } from './social/profile.js';
 export { default as InsetImage } from './components/InsetImage.svelte';
 export { default as Badge } from './components/Badge.svelte';
 export { default as Modal } from './components/Modal.svelte';

package/dist/index.js

@@ -3,6 +3,8 @@ export { default as IconButton } from './components/IconButton.svelte';
 export { default as Input } from './components/Input.svelte';
 export { default as Textarea } from './components/Textarea.svelte';
 export { default as Select } from './components/Select.svelte';
+export { default as SocialClientPicker } from './components/SocialClientPicker.svelte';
+export * from './social.js';
 export { default as Checkbox } from './components/Checkbox.svelte';
 export { default as Label } from './components/Label.svelte';
 export { default as PageTitle } from './components/PageTitle.svelte';
@@ -10,6 +12,8 @@ export { default as Heading } from './components/Heading.svelte';
 export { default as Subheading } from './components/Subheading.svelte';
 export { default as Surface } from './components/Surface.svelte';
 export { default as Avatar } from './components/Avatar.svelte';
+export { default as UserProfile } from './components/UserProfile.svelte';
+export { blueskyProfileToProfileData } from './social/profile.js';
 export { default as InsetImage } from './components/InsetImage.svelte';
 export { default as Badge } from './components/Badge.svelte';
 export { default as Modal } from './components/Modal.svelte';

package/dist/lexicons/social.atmo.actor.preferredClient.json

@@ -0,0 +1,29 @@
+{
+	"lexicon": 1,
+	"id": "social.atmo.actor.preferredClient",
+	"defs": {
+		"main": {
+			"type": "record",
+			"description": "An actor's public preferred Bluesky-compatible social client. Other preferences belong in separate records.",
+			"key": "literal:self",
+			"record": {
+				"type": "object",
+				"required": ["client"],
+				"properties": {
+					"client": {
+						"type": "string",
+						"description": "The preferred social client. custom requires customUrl.",
+						"knownValues": ["bluesky", "mu", "blacksky", "witchsky", "custom"],
+						"maxLength": 64
+					},
+					"customUrl": {
+						"type": "string",
+						"format": "uri",
+						"maxLength": 2048,
+						"description": "For custom clients only: an absolute HTTP(S) base URL without credentials, query or fragment. Must support /profile/:actor links."
+					}
+				}
+			}
+		}
+	}
+}

package/dist/social/preferred-client.d.ts

@@ -0,0 +1,36 @@
+/** Public, cross-app social-client selection in the actor's repository. */
+export declare const PREFERRED_CLIENT_COLLECTION = "social.atmo.actor.preferredClient";
+export declare const PREFERRED_CLIENT_RKEY = "self";
+export declare const PREFERRED_CLIENT_SCOPE = "repo:social.atmo.actor.preferredClient?action=create&action=update";
+export declare const socialClients: readonly [{
+    readonly id: "bluesky";
+    readonly label: "Bluesky";
+    readonly url: "https://bsky.app";
+}, {
+    readonly id: "mu";
+    readonly label: "mu";
+    readonly url: "https://mu.social";
+}, {
+    readonly id: "blacksky";
+    readonly label: "Blacksky";
+    readonly url: "https://blacksky.community";
+}, {
+    readonly id: "witchsky";
+    readonly label: "Witchsky";
+    readonly url: "https://witchsky.app";
+}];
+export type SocialClientId = (typeof socialClients)[number]['id'] | 'custom';
+export type PreferredSocialClient = {
+    client: Exclude<SocialClientId, 'custom'>;
+} | {
+    client: 'custom';
+    customUrl: string;
+};
+/** Require an absolute web URL. Keep path prefixes for self-hosted clients. */
+export declare function normalizeSocialClientUrl(value: string): string | null;
+export declare function parsePreferredSocialClient(value: unknown): PreferredSocialClient | null;
+export declare function preferredSocialClientRecord(preference: PreferredSocialClient): Record<string, unknown>;
+export declare function socialClientInfo(preference?: PreferredSocialClient | null): {
+    label: string;
+    url: string;
+};

package/dist/social/preferred-client.js

@@ -0,0 +1,48 @@
+/** Public, cross-app social-client selection in the actor's repository. */
+export const PREFERRED_CLIENT_COLLECTION = 'social.atmo.actor.preferredClient';
+export const PREFERRED_CLIENT_RKEY = 'self';
+export const PREFERRED_CLIENT_SCOPE = `repo:${PREFERRED_CLIENT_COLLECTION}?action=create&action=update`;
+export const socialClients = [
+    { id: 'bluesky', label: 'Bluesky', url: 'https://bsky.app' },
+    { id: 'mu', label: 'mu', url: 'https://mu.social' },
+    { id: 'blacksky', label: 'Blacksky', url: 'https://blacksky.community' },
+    { id: 'witchsky', label: 'Witchsky', url: 'https://witchsky.app' }
+];
+/** Require an absolute web URL. Keep path prefixes for self-hosted clients. */
+export function normalizeSocialClientUrl(value) {
+    try {
+        const url = new URL(value.trim());
+        if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+            return null;
+        if (url.search || url.hash || url.href.length > 2048)
+            return null;
+        return url.href.replace(/\/+$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+export function parsePreferredSocialClient(value) {
+    if (!value || typeof value !== 'object' || !('client' in value))
+        return null;
+    if (value.client === 'custom') {
+        const customUrl = 'customUrl' in value && typeof value.customUrl === 'string'
+            ? normalizeSocialClientUrl(value.customUrl)
+            : null;
+        return customUrl ? { client: 'custom', customUrl } : null;
+    }
+    const client = socialClients.find((client) => client.id === value.client);
+    return client ? { client: client.id } : null;
+}
+export function preferredSocialClientRecord(preference) {
+    const client = parsePreferredSocialClient(preference);
+    if (!client)
+        throw new Error('Choose a client and enter a valid client URL.');
+    return { $type: PREFERRED_CLIENT_COLLECTION, ...client };
+}
+export function socialClientInfo(preference) {
+    const client = parsePreferredSocialClient(preference) ?? { client: 'bluesky' };
+    return client.client === 'custom'
+        ? { label: 'Custom client', url: client.customUrl }
+        : socialClients.find((entry) => entry.id === client.client);
+}

package/dist/social/profile.d.ts

@@ -0,0 +1,36 @@
+import type { PreferredSocialClient } from './preferred-client.js';
+/** Hydrated app.bsky.actor.link data, not the legacy profile.website field. */
+export type ProfileLink = {
+    url: string;
+    title?: string;
+    icon?: string;
+};
+export type ProfileData = {
+    did: string;
+    handle?: string;
+    displayName?: string;
+    avatar?: string;
+    banner?: string;
+    description?: string;
+    pronouns?: string;
+    links?: ProfileLink[];
+    followersCount?: number;
+    followsCount?: number;
+    postsCount?: number;
+    createdAt?: string;
+};
+/** Only web URLs; never accept executable schemes or disguised credentials. */
+export declare function safeProfileUrl(value: string | undefined): string | undefined;
+/** Bios are plain text with detected facets, never HTML or Markdown. No network requests. */
+export type ProfileDescriptionOptions = {
+    socialClient?: PreferredSocialClient | null;
+    /** App-owned mention destination; omit to use the selected social client. */
+    mentionUrl?: (identifier: string) => string;
+};
+export declare function profileDescriptionSegments(text: string, options?: ProfileDescriptionOptions): {
+    text: string;
+    href: string | undefined;
+}[];
+export declare function visibleProfileLinks(links?: ProfileLink[]): ProfileLink[];
+/** Validate public AppView data at the boundary, including newer optional fields. */
+export declare function blueskyProfileToProfileData(value: unknown): ProfileData | undefined;

package/dist/social/profile.js

@@ -0,0 +1,78 @@
+import { tokenize } from '@atcute/bluesky-richtext-parser';
+import { safeWebUrl } from './richtext.js';
+import { socialHashtagUrl, socialProfileUrl } from './urls.js';
+/** Only web URLs; never accept executable schemes or disguised credentials. */
+export function safeProfileUrl(value) {
+    if (!value ||
+        Array.from(value).some((char) => char.charCodeAt(0) <= 0x20 || char.charCodeAt(0) === 0x7f))
+        return undefined;
+    const href = safeWebUrl(value);
+    if (!href)
+        return undefined;
+    const url = new URL(href);
+    return url.username || url.password ? undefined : href;
+}
+export function profileDescriptionSegments(text, options = {}) {
+    return Array.from(tokenize(text), (token) => ({
+        text: token.raw,
+        href: token.type === 'autolink'
+            ? safeProfileUrl(token.url)
+            : token.type === 'mention'
+                ? (options.mentionUrl?.(token.handle) ??
+                    socialProfileUrl(token.handle, options.socialClient))
+                : token.type === 'topic'
+                    ? socialHashtagUrl(token.name, options.socialClient)
+                    : undefined
+    }));
+}
+export function visibleProfileLinks(links = []) {
+    const seen = new Set();
+    const result = [];
+    for (const link of links) {
+        const url = safeProfileUrl(link.url);
+        if (!url || seen.has(url))
+            continue;
+        seen.add(url);
+        result.push({ url, title: link.title?.trim() || undefined, icon: safeProfileUrl(link.icon) });
+        if (result.length === 10)
+            break;
+    }
+    return result;
+}
+/** Validate public AppView data at the boundary, including newer optional fields. */
+export function blueskyProfileToProfileData(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const p = value;
+    if (typeof p.did !== 'string' || !p.did.startsWith('did:'))
+        return undefined;
+    const text = (key) => (typeof p[key] === 'string' ? p[key] : undefined);
+    const count = (key) => typeof p[key] === 'number' && Number.isSafeInteger(p[key]) && p[key] >= 0 ? p[key] : undefined;
+    const links = [];
+    for (const item of Array.isArray(p.links) ? p.links : []) {
+        if (!item || typeof item !== 'object' || typeof item.url !== 'string')
+            continue;
+        // Without viewer-specific moderation preferences, omit labeled links conservatively.
+        if (Array.isArray(item.labels) && item.labels.some((label) => !label?.neg))
+            continue;
+        links.push({
+            url: item.url,
+            title: typeof item.title === 'string' ? item.title : undefined,
+            icon: typeof item.icon === 'string' ? item.icon : undefined
+        });
+    }
+    return {
+        did: p.did,
+        handle: text('handle'),
+        displayName: text('displayName'),
+        avatar: safeProfileUrl(text('avatar')),
+        banner: safeProfileUrl(text('banner')),
+        description: text('description'),
+        pronouns: text('pronouns'),
+        links: visibleProfileLinks(links),
+        followersCount: count('followersCount'),
+        followsCount: count('followsCount'),
+        postsCount: count('postsCount'),
+        createdAt: text('createdAt')
+    };
+}

package/dist/social/urls.d.ts

@@ -1,2 +1,9 @@
+import { type PreferredSocialClient } from './preferred-client.js';
 /** Bluesky expects literal DIDs in its routes, including colons and did:web escapes. */
 export declare function blueskyProfileUrl(identifier: string): string;
+/** Supported clients share Bluesky's /profile/:actor route. */
+export declare function socialProfileUrl(identifier: string, client?: PreferredSocialClient | null): string;
+/** Open a hashtag in the viewer's preferred Bluesky-compatible client. */
+export declare function socialHashtagUrl(tag: string, client?: PreferredSocialClient | null): string;
+/** Open a feed-post AT URI in the viewer's preferred Bluesky-compatible client. */
+export declare function socialPostUrl(uri: string, client?: PreferredSocialClient | null): string | null;

package/dist/social/urls.js

@@ -1,6 +1,22 @@
-import { isDid } from '@atcute/lexicons/syntax';
+import { isActorIdentifier, isDid, isRecordKey } from '@atcute/lexicons/syntax';
+import { socialClientInfo } from './preferred-client.js';
 /** Bluesky expects literal DIDs in its routes, including colons and did:web escapes. */
 export function blueskyProfileUrl(identifier) {
+    return socialProfileUrl(identifier);
+}
+/** Supported clients share Bluesky's /profile/:actor route. */
+export function socialProfileUrl(identifier, client) {
     const actor = isDid(identifier) ? identifier : encodeURIComponent(identifier);
-    return `https://bsky.app/profile/${actor}`;
+    return `${socialClientInfo(client).url}/profile/${actor}`;
+}
+/** Open a hashtag in the viewer's preferred Bluesky-compatible client. */
+export function socialHashtagUrl(tag, client) {
+    return `${socialClientInfo(client).url}/hashtag/${encodeURIComponent(tag)}`;
+}
+/** Open a feed-post AT URI in the viewer's preferred Bluesky-compatible client. */
+export function socialPostUrl(uri, client) {
+    const match = /^at:\/\/([^/]+)\/app\.bsky\.feed\.post\/([^/]+)$/.exec(uri);
+    if (!match || !isActorIdentifier(match[1]) || !isRecordKey(match[2]))
+        return null;
+    return `${socialProfileUrl(match[1], client)}/post/${encodeURIComponent(match[2])}`;
 }

package/dist/social.d.ts

@@ -0,0 +1,3 @@
+export { PREFERRED_CLIENT_COLLECTION, PREFERRED_CLIENT_RKEY, PREFERRED_CLIENT_SCOPE, socialClients, normalizeSocialClientUrl, parsePreferredSocialClient, preferredSocialClientRecord, socialClientInfo } from './social/preferred-client.js';
+export type { SocialClientId, PreferredSocialClient } from './social/preferred-client.js';
+export { blueskyProfileUrl, socialProfileUrl, socialPostUrl, socialHashtagUrl } from './social/urls.js';

package/dist/social.js

@@ -0,0 +1,2 @@
+export { PREFERRED_CLIENT_COLLECTION, PREFERRED_CLIENT_RKEY, PREFERRED_CLIENT_SCOPE, socialClients, normalizeSocialClientUrl, parsePreferredSocialClient, preferredSocialClientRecord, socialClientInfo } from './social/preferred-client.js';
+export { blueskyProfileUrl, socialProfileUrl, socialPostUrl, socialHashtagUrl } from './social/urls.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atmo-dev/kit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The shared UI foundation for Atmo apps.",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,11 @@
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./social": {
+      "types": "./dist/social.d.ts",
+      "default": "./dist/social.js"
+    },
+    "./lexicons/social.atmo.actor.preferredClient.json": "./dist/lexicons/social.atmo.actor.preferredClient.json",
     "./legal": {
       "types": "./dist/legal.d.ts",
       "default": "./dist/legal.js"