@atmo-dev/kit 0.5.0 → 0.7.0

package/README.md

@@ -9,6 +9,97 @@ 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).
 
+## Navigation
+
+`IconRail` items accept a `variant` from `Button` (`primary`, `secondary`, `ghost`,
+`link`); omitted variants remain `ghost`. Use `primary: true, variant: 'primary'`
+for a separated, filled creation action in the rail, mobile bar or drawer. The
+existing `primary` flag alone retains its subtle accent/spacing behavior.
+
+## AT record metadata (AT Tags)
+
+Use `AtTags` to let other clients discover which AT Protocol records and identities
+an HTML page represents. It renders server-side `<meta name="at:…" content="at://…">`
+tags in the document head and updates/removes them when its props change. It needs
+no theme, styles, network requests, or app state.
+
+The [AT Tags proposal](https://tangled.org/chrisshank.com/at-tags) is a draft. Its four
+standard relationships are:
+
+| Property    | Meaning                                                                  | Content         |
+| ----------- | ------------------------------------------------------------------------ | --------------- |
+| `canonical` | The record this page represents; deleting it would remove the page.      | A record AT URI |
+| `alternate` | Auxiliary records shown or referenced; the page survives their deletion. | A record AT URI |
+| `author`    | Account(s) who authored the page's content.                              | `at://<DID>`    |
+| `me`        | Account(s) this site or section belongs to.                              | `at://<DID>`    |
+
+Each property accepts an array; multiple values produce separate tags, with exact
+duplicates removed within each property. Use meta **names**, not Open Graph
+`property` attributes or `<link href="at://…">`. These tags supplement—not
+replace—your title, description, HTTPS canonical URL and Open Graph metadata.
+
+For a page backed by one record authored by its repository owner, use the
+framework-free `recordAtTags` helper in your server loader:
+
+```ts
+import { recordAtTags } from '@atmo-dev/kit/at-tags';
+
+// After app-owned loading, visibility/moderation checks and handle resolution:
+return {
+	atTags: recordAtTags(record, relatedRecords)
+};
+```
+
+`record` and each optional `relatedRecords` entry only need `{ uri: string }`.
+The helper sets `canonical`, derives `author` from the record's repository DID,
+and lists related records as `alternate`, excluding the canonical URI. It throws
+`SyntaxError` for non-record or handle-based URIs: pass resolved DID-based record
+URIs, not a URL path or viewer parameter. It does not resolve or fetch anything.
+
+Render the metadata once in a SvelteKit root layout (covering embeds too):
+
+```svelte
+<script lang="ts">
+	import { page } from '$app/state';
+	import { AtTags } from '@atmo-dev/kit';
+
+	let { children } = $props();
+</script>
+
+<AtTags tags={page.error ? undefined : page.data.atTags} />
+{@render children()}
+```
+
+Add `atTags?: import('@atmo-dev/kit/at-tags').AtTagMetadata` to `App.PageData`.
+In other Svelte apps, pass the current page's metadata directly; set `tags` to
+`undefined` on pages with no relationships. Do not mount competing tag owners.
+
+You can supply `AtTagMetadata` directly for multiple canonical records, different
+or additional authors, or an account section:
+
+```ts
+import type { AtTagMetadata } from '@atmo-dev/kit/at-tags';
+
+const atTags: AtTagMetadata = {
+	me: [`at://${profile.did}`],
+	alternate: profile.uri ? [profile.uri] : []
+};
+```
+
+An account's events page might survive deletion of its optional Bluesky profile,
+so that profile record is an alternate, not necessarily canonical. Likewise,
+embedded comments are alternate records, not the page's authors. `me` is not the
+signed-in viewer or every record author; do not assign it site-wide unless the
+site actually belongs to that account. Ordinary discovery and creation pages
+usually have no canonical record.
+
+Apps own these semantic choices, record loading, identity resolution, visibility,
+and error-page suppression. The component escapes attributes but does not validate
+raw metadata or verify record existence. Use record URIs with collection and rkey,
+and bare `at://<DID>` identity URIs without a trailing slash. Only the four standard
+properties are supported; parsing/scraping pages and draft custom namespaces are
+outside this API.
+
 ## Events
 
 The event UI formerly in `@atmo-dev/events-ui` lives in this package:
@@ -30,6 +121,8 @@ The event UI formerly in `@atmo-dev/events-ui` lives in this package:
 - `@atmo-dev/kit/events-data`: structural event types, adapter contracts, conference/date helpers, URL helpers, theme values, linked-record types and thumbnail selection. This entry is safe in plain Node and server routes: no Svelte, CSS, maps or players are loaded. Browser helpers such as `compressImage` only access browser APIs when called.
 - `@atmo-dev/kit/events/editor`: `buildEventRecord` and `buildThumbnailMedia` for hosts that need explicit record construction. This separate entry includes browser-oriented thumbnail code; it is not part of the pure data API.
 
+Event cards and covers prefer native `media` images, then an HTTPS `poster.url`, then a URI named `Event Image` (laugh.town compatibility). `getEventExternalImage(event)` from `events-data` returns `{ url, alt, aspectRatio? }` or `null`, validating URLs and optional poster dimensions. It performs no IO; apps must apply their own allowlist/redirect policy before fetching an external image server-side.
+
 Apps implement `EditorAdapter` for authentication prompts, repository IO, uploads, save/delete navigation, and optional linked-record transport/indexing notifications. Keep sessions, Cloudflare bindings, app routes, server endpoints, caching and moderation in the app. The editor/view never imports a consumer's app state. Existing `EventView` page-data shape and RSVP behavior are preserved in this migration.
 
 Full event UI requires optional peers (ordinary Kit consumers do not):

package/dist/at-tags.d.ts

@@ -0,0 +1,18 @@
+/** Standard AT Tags draft properties. Identity values are `at://<DID>` URIs. */
+export interface AtTagMetadata {
+    canonical?: readonly string[];
+    alternate?: readonly string[];
+    author?: readonly string[];
+    me?: readonly string[];
+}
+/** A resolved record reference; no lexicon-specific fields are needed. */
+export interface AtTagRecordRef {
+    uri: string;
+}
+/**
+ * Metadata for a page backed by one record, authored by its repository owner.
+ * Supply only auxiliary records represented on the page. Throws SyntaxError for
+ * non-record or non-DID-based URIs; resolve handles before calling this helper.
+ * For multiple canonical records or different authors, supply metadata directly.
+ */
+export declare function recordAtTags(record: AtTagRecordRef, alternates?: readonly AtTagRecordRef[]): AtTagMetadata;

package/dist/at-tags.js

@@ -0,0 +1,18 @@
+import { parseCanonicalResourceUri } from '@atcute/lexicons/syntax';
+/**
+ * Metadata for a page backed by one record, authored by its repository owner.
+ * Supply only auxiliary records represented on the page. Throws SyntaxError for
+ * non-record or non-DID-based URIs; resolve handles before calling this helper.
+ * For multiple canonical records or different authors, supply metadata directly.
+ */
+export function recordAtTags(record, alternates = []) {
+    const { repo } = parseCanonicalResourceUri(record.uri);
+    const alternate = [...new Set(alternates.map(({ uri }) => uri))].filter((uri) => uri !== record.uri);
+    for (const uri of alternate)
+        parseCanonicalResourceUri(uri);
+    return {
+        canonical: [record.uri],
+        author: [`at://${repo}`],
+        alternate
+    };
+}

package/dist/components/AtTags.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import type { AtTagMetadata } from '../at-tags.js';
+
+	export interface AtTagsProps {
+		tags?: AtTagMetadata;
+	}
+
+	let { tags }: AtTagsProps = $props();
+</script>
+
+<svelte:head>
+	{#each ['canonical', 'alternate', 'author', 'me'] as property (property)}
+		{#each [...new Set(tags?.[property as keyof AtTagMetadata] ?? [])] as uri (uri)}
+			<meta name={`at:${property}`} content={uri} />
+		{/each}
+	{/each}
+</svelte:head>

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

@@ -0,0 +1,7 @@
+import type { AtTagMetadata } from '../at-tags.js';
+export interface AtTagsProps {
+    tags?: AtTagMetadata;
+}
+declare const AtTags: import("svelte").Component<AtTagsProps, {}, "">;
+type AtTags = ReturnType<typeof AtTags>;
+export default AtTags;

package/dist/components/IconRail.svelte

@@ -1,7 +1,7 @@
 <script lang="ts" module>
 	import type { IconNode } from '@sketchyicons/svelte';
 	import type { ButtonProps } from './Button.svelte';
-	export type IconRailItem = Pick<ButtonProps, 'href' | 'onclick' | 'disabled'> & {
+	export type IconRailItem = Pick<ButtonProps, 'href' | 'onclick' | 'disabled' | 'variant'> & {
 		label: string;
 		icon: IconNode;
 		active?: boolean;
@@ -77,7 +77,7 @@
 					<Button
 						href={item.href}
 						disabled={item.disabled}
-						variant="ghost"
+						variant={item.variant ?? 'ghost'}
 						aria-current={item.active ? 'page' : undefined}
 						data-part="item"
 						onclick={(event) => {
@@ -85,8 +85,11 @@
 							item.onclick?.(event);
 						}}
 						class={cn(
-							'min-h-11 w-full justify-start gap-3 px-3 py-3 text-sm aria-[current=page]:bg-recess aria-[current=page]:text-action',
-							item.primary && 'mt-3 text-action'
+							'min-h-11 w-full justify-start gap-3 px-3 py-3 text-sm',
+							(!item.variant || item.variant === 'ghost') &&
+								'aria-[current=page]:bg-recess aria-[current=page]:text-action',
+							item.primary && 'mt-3',
+							item.primary && (!item.variant || item.variant === 'ghost') && 'text-action'
 						)}
 					>
 						<Icon img={item.icon} size={22} />
@@ -128,15 +131,22 @@
 									{...props}
 									href={item.href}
 									disabled={item.disabled}
-									variant="ghost"
+									variant={item.variant ?? 'ghost'}
 									size="icon"
 									aria-label={`${item.label}${item.badge ? (typeof item.badge === 'number' ? `, ${item.badge} unread` : ', unread') : ''}`}
 									aria-current={item.active ? 'page' : undefined}
 									data-part="item"
 									class={cn(
-										'relative size-11 rounded-(--atmo-radius-button) text-muted hover:bg-recess/55 aria-[current=page]:text-action max-sm:size-10',
-										item.primary && 'mt-2 text-action hover:text-action max-sm:mt-0',
-										backed && 'bg-recess/45 hover:bg-recess/75'
+										'relative size-11 rounded-(--atmo-radius-button) max-sm:size-10',
+										(!item.variant || item.variant === 'ghost') &&
+											'text-muted hover:bg-recess/55 aria-[current=page]:text-action',
+										item.primary && 'mt-2 max-sm:mt-0',
+										item.primary &&
+											(!item.variant || item.variant === 'ghost') &&
+											'text-action hover:text-action',
+										backed &&
+											(!item.variant || item.variant === 'ghost') &&
+											'bg-recess/45 hover:bg-recess/75'
 									)}
 								>
 									<Icon img={item.icon} size={22} />{#if item.badge}<span

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

@@ -1,6 +1,6 @@
 import type { IconNode } from '@sketchyicons/svelte';
 import type { ButtonProps } from './Button.svelte';
-export type IconRailItem = Pick<ButtonProps, 'href' | 'onclick' | 'disabled'> & {
+export type IconRailItem = Pick<ButtonProps, 'href' | 'onclick' | 'disabled' | 'variant'> & {
     label: string;
     icon: IconNode;
     active?: boolean;

package/dist/events/EventCard.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { getCDNImageBlobUrl } from './atproto-helpers.js';
-	import { getEventThumbnail } from './event-media.js';
+	import { getEventThumbnail, getEventExternalImage } from './event-media.js';
 	import { eventUrl, isEventOngoing, type FlatEventRecord } from './contrail.js';
 	import Avatar from 'svelte-boring-avatars';
 	import { Badge, Icon } from '../index.js';
@@ -75,7 +75,7 @@
 			if (url) return { url, alt: banner.alt || event.name };
 		}
 
-		return null;
+		return getEventExternalImage(event);
 	}
 
 	let thumbnail = $derived(getThumbnail(event));

package/dist/events/EventView.svelte

@@ -2,7 +2,7 @@
 	import { eventUrl, isEventOngoing, type FlatEventRecord } from './contrail.js';
 	import type { EventViewData } from './view-data.js';
 	import { getCDNImageBlobUrl } from './atproto-helpers.js';
-	import { getEventThumbnail } from './event-media.js';
+	import { getEventThumbnail, getEventExternalImage } from './event-media.js';
 	import { Button, ToggleGroup, ToggleGroupItem } from '../index.js';
 	import ShareModal from './ShareModal.svelte';
 	import EventComments from './EventComments.svelte';
@@ -159,8 +159,8 @@
 		return { url, alt: media.alt || eventData.name, aspectRatio: media.aspect_ratio };
 	});
 
-	// Prefer thumbnail, then flyer; fall back to header/banner image.
-	let displayImage = $derived(thumbnailImage ?? bannerImage);
+	// Prefer native media, then external posters.
+	let displayImage = $derived(thumbnailImage ?? bannerImage ?? getEventExternalImage(eventData));
 	let imageAspectRatio = $derived.by(() => {
 		const ratio = displayImage?.aspectRatio;
 		if (!ratio || ratio.width <= 0 || ratio.height <= 0) return null;

package/dist/events/event-media.d.ts

@@ -2,3 +2,19 @@
 export declare function getEventThumbnail<T extends {
     role?: unknown;
 }>(media: readonly T[] | null | undefined): T | undefined;
+export type ExternalEventImage = {
+    url: string;
+    alt: string;
+    aspectRatio?: {
+        width: number;
+        height: number;
+    };
+};
+/** External poster compatibility (e.g. laugh.town). Prefer native media first.
+ * Validates display URLs only; apps must apply their own server-fetch policy.
+ */
+export declare function getEventExternalImage(event: {
+    name: string;
+    poster?: unknown;
+    uris?: unknown;
+}): ExternalEventImage | null;

package/dist/events/event-media.js

@@ -2,3 +2,48 @@
 export function getEventThumbnail(media) {
     return media?.find((m) => m.role === 'thumbnail') ?? media?.find((m) => m.role === 'flyer');
 }
+function imageUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        return url.href;
+    }
+    catch {
+        return null;
+    }
+}
+/** External poster compatibility (e.g. laugh.town). Prefer native media first.
+ * Validates display URLs only; apps must apply their own server-fetch policy.
+ */
+export function getEventExternalImage(event) {
+    const poster = event.poster;
+    if (poster && typeof poster === 'object' && 'url' in poster) {
+        const url = imageUrl(poster.url);
+        if (url) {
+            const width = 'width' in poster ? poster.width : undefined;
+            const height = 'height' in poster ? poster.height : undefined;
+            const aspectRatio = typeof width === 'number' &&
+                Number.isFinite(width) &&
+                width > 0 &&
+                typeof height === 'number' &&
+                Number.isFinite(height) &&
+                height > 0
+                ? { width, height }
+                : undefined;
+            return { url, alt: event.name, aspectRatio };
+        }
+    }
+    if (Array.isArray(event.uris)) {
+        for (const link of event.uris) {
+            if (!link || typeof link !== 'object' || link.name !== 'Event Image')
+                continue;
+            const url = imageUrl(link.uri);
+            if (url)
+                return { url, alt: event.name };
+        }
+    }
+    return null;
+}

package/dist/events/event-types.d.ts

@@ -35,6 +35,8 @@ export type EventData = EventLexiconMain & {
         uri: string;
         name?: string;
     }>;
+    /** External poster extension used by laugh.town; validated when displayed. */
+    poster?: unknown;
     media?: Array<{
         role: string;
         alt?: string;

package/dist/events-data.d.ts

@@ -9,7 +9,7 @@ export * from './events/conference.js';
 export * from './events/linked-records.js';
 export * from './events/date-format.js';
 export * from './events/theme.js';
-export { getEventThumbnail } from './events/event-media.js';
+export { getEventThumbnail, getEventExternalImage, type ExternalEventImage } from './events/event-media.js';
 export { getCDNImageBlobUrl, compressImage } from './events/atproto-helpers.js';
 export { getProfileUrl, getLocalProfileUrl } from './events/profile-url.js';
 export { normalizeCountryCode, normalizeEventLocations, LocationValidationError } from './events/editor/location.js';

package/dist/events-data.js

@@ -3,7 +3,7 @@ export * from './events/conference.js';
 export * from './events/linked-records.js';
 export * from './events/date-format.js';
 export * from './events/theme.js';
-export { getEventThumbnail } from './events/event-media.js';
+export { getEventThumbnail, getEventExternalImage } from './events/event-media.js';
 export { getCDNImageBlobUrl, compressImage } from './events/atproto-helpers.js';
 export { getProfileUrl, getLocalProfileUrl } from './events/profile-url.js';
 export { normalizeCountryCode, normalizeEventLocations, LocationValidationError } from './events/editor/location.js';

package/dist/index.d.ts

@@ -11,6 +11,9 @@ 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';
+export { default as AtTags } from './components/AtTags.svelte';
+export type { AtTagsProps } from './components/AtTags.svelte';
+export * from './at-tags.js';
 export { default as Heading } from './components/Heading.svelte';
 export { default as Subheading } from './components/Subheading.svelte';
 export { default as Surface } from './components/Surface.svelte';

package/dist/index.js

@@ -8,6 +8,8 @@ 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';
+export { default as AtTags } from './components/AtTags.svelte';
+export * from './at-tags.js';
 export { default as Heading } from './components/Heading.svelte';
 export { default as Subheading } from './components/Subheading.svelte';
 export { default as Surface } from './components/Surface.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atmo-dev/kit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The shared UI foundation for Atmo apps.",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,10 @@
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./at-tags": {
+      "types": "./dist/at-tags.d.ts",
+      "default": "./dist/at-tags.js"
+    },
     "./events": {
       "types": "./dist/events.d.ts",
       "svelte": "./dist/events.js",
@@ -166,7 +170,7 @@
     "test": "pnpm test:unit --run && pnpm test:e2e && pnpm test:package",
     "test:ci": "pnpm test:unit --run --no-file-parallelism && pnpm test:e2e && pnpm test:package",
     "test:e2e": "playwright test",
-    "test:package": "pnpm prepack && node --test scripts/test-events-package.mjs",
+    "test:package": "pnpm prepack && node --test scripts/test-*-package.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version && pnpm install --lockfile-only --no-frozen-lockfile --ignore-scripts",
     "release": "pnpm prepack && changeset publish"