@atmo-dev/kit 0.5.0 → 0.6.0

package/README.md

@@ -9,6 +9,90 @@ 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).
 
+## 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:

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/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.6.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"