@tangle-network/brand 1.26.2 → 1.27.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.27.1
+
+### Patch Changes
+
+- e652c36: Expose social metadata declarations to TypeScript consumers using legacy Node
+  module resolution. The modern package export, runtime code and styles stay the same.
+
+## 1.27.0
+
+### Minor Changes
+
+- 3527225: Publish framework-neutral social metadata for server-rendered and static product pages. Keep the poster fallback, canonical URL, alt text and optional video properties together without importing React or claiming social-client playback.
+
 ## 1.26.2
 
 ### Patch Changes

package/README.md

@@ -10,6 +10,24 @@ pnpm add @tangle-network/brand
 
 ## Use
 
+### Social previews
+
+`@tangle-network/brand/social` is framework-neutral. Pass the page's existing
+copy and verified media to `socialMetadata({ url, title, description, image,
+video? })`. The image requires its public HTTPS `url`, MIME `type`, measured
+pixel `width`/`height` and descriptive `alt`; an optional video requires the same
+media fields except alt. Render the returned `tags` in the server/static head
+and use `canonicalUrl` for the canonical link. Each tag has either `property`
+or `name`, plus `content`; the consumer's HTML renderer owns escaping.
+
+Keep product-specific composition and media approval with their existing
+owners. Brand owns the common tag contract; callers supply the approved asset
+URLs. The default X card retains the image fallback. Do not infer video playback
+from metadata or switch to a platform-specific player without that platform's
+current supported contract and a real preview check. This helper does not fetch
+media, prove its MIME/codec/duration/range/cache behavior, or approve publication.
+Verify those against the served files. Canonical URLs omit query and fragment.
+
 ### Tailwind v4
 
 ```css

package/dist/social.d.ts

@@ -0,0 +1,40 @@
+//#region src/social.d.ts
+export interface SocialImage {
+  url: string;
+  type: "image/png" | "image/jpeg" | "image/webp";
+  width: number;
+  height: number;
+  alt: string;
+}
+export interface SocialVideo {
+  url: string;
+  type: "video/mp4" | "video/webm";
+  width: number;
+  height: number;
+}
+export interface SocialPage {
+  url: string;
+  title: string;
+  description: string;
+  image: SocialImage;
+  video?: SocialVideo;
+  type?: "website" | "article";
+  siteName?: string;
+}
+export type SocialMetaTag = {
+  property: string;
+  content: string;
+  name?: never;
+} | {
+  name: string;
+  content: string;
+  property?: never;
+};
+/** Render these tags in the server/static head, never after hydration.
+ * Video metadata advertises an asset; a social client's playback needs its own proof.
+ */
+export declare function socialMetadata(page: SocialPage): {
+  canonicalUrl: string;
+  tags: SocialMetaTag[];
+};
+//#endregion

package/dist/social.js

@@ -0,0 +1,109 @@
+//#region src/social.ts
+function httpsUrl(value) {
+	const url = new URL(value);
+	if (url.protocol !== "https:" || url.username || url.password) throw new Error("Social metadata requires HTTPS URLs without credentials");
+	return url;
+}
+function mediaTags(kind, media) {
+	const url = httpsUrl(media.url).href;
+	if (![media.width, media.height].every((size) => Number.isSafeInteger(size) && size > 0)) throw new Error(`Social ${kind} dimensions must be positive pixel counts`);
+	if (!(kind === "image" ? [
+		"image/png",
+		"image/jpeg",
+		"image/webp"
+	] : ["video/mp4", "video/webm"]).includes(media.type)) throw new Error(`Unsupported social ${kind} MIME type`);
+	return [
+		{
+			property: `og:${kind}`,
+			content: url
+		},
+		{
+			property: `og:${kind}:secure_url`,
+			content: url
+		},
+		{
+			property: `og:${kind}:type`,
+			content: media.type
+		},
+		{
+			property: `og:${kind}:width`,
+			content: String(media.width)
+		},
+		{
+			property: `og:${kind}:height`,
+			content: String(media.height)
+		}
+	];
+}
+/** Render these tags in the server/static head, never after hydration.
+* Video metadata advertises an asset; a social client's playback needs its own proof.
+*/
+function socialMetadata(page) {
+	for (const text of [
+		page.title,
+		page.description,
+		page.image.alt
+	]) if (!text.trim()) throw new Error("Social title, description and image alt must be nonempty");
+	const canonical = httpsUrl(page.url);
+	canonical.search = "";
+	canonical.hash = "";
+	const canonicalUrl = canonical.href;
+	const imageUrl = httpsUrl(page.image.url).href;
+	return {
+		canonicalUrl,
+		tags: [
+			{
+				property: "og:type",
+				content: page.type ?? "website"
+			},
+			{
+				property: "og:site_name",
+				content: page.siteName ?? "Tangle"
+			},
+			{
+				property: "og:url",
+				content: canonicalUrl
+			},
+			{
+				property: "og:title",
+				content: page.title
+			},
+			{
+				property: "og:description",
+				content: page.description
+			},
+			...mediaTags("image", page.image),
+			{
+				property: "og:image:alt",
+				content: page.image.alt
+			},
+			...page.video ? mediaTags("video", page.video) : [],
+			{
+				name: "twitter:card",
+				content: "summary_large_image"
+			},
+			{
+				name: "twitter:site",
+				content: "@tangle_network"
+			},
+			{
+				name: "twitter:title",
+				content: page.title
+			},
+			{
+				name: "twitter:description",
+				content: page.description
+			},
+			{
+				name: "twitter:image",
+				content: imageUrl
+			},
+			{
+				name: "twitter:image:alt",
+				content: page.image.alt
+			}
+		]
+	};
+}
+//#endregion
+export { socialMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.26.2",
+  "version": "1.27.1",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,13 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "typesVersions": {
+    "*": {
+      "social": [
+        "dist/social.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -50,6 +57,11 @@
       "import": "./dist/knot.js",
       "default": "./dist/knot.js"
     },
+    "./social": {
+      "types": "./dist/social.d.ts",
+      "import": "./dist/social.js",
+      "default": "./dist/social.js"
+    },
     "./styles/presentation.css": "./src/styles/presentation.css"
   },
   "peerDependencies": {

package/src/social.ts

@@ -0,0 +1,93 @@
+export interface SocialImage {
+  url: string;
+  type: "image/png" | "image/jpeg" | "image/webp";
+  width: number;
+  height: number;
+  alt: string;
+}
+
+export interface SocialVideo {
+  url: string;
+  type: "video/mp4" | "video/webm";
+  width: number;
+  height: number;
+}
+
+export interface SocialPage {
+  url: string;
+  title: string;
+  description: string;
+  image: SocialImage;
+  video?: SocialVideo;
+  type?: "website" | "article";
+  siteName?: string;
+}
+
+export type SocialMetaTag =
+  | { property: string; content: string; name?: never }
+  | { name: string; content: string; property?: never };
+
+function httpsUrl(value: string): URL {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password) {
+    throw new Error("Social metadata requires HTTPS URLs without credentials");
+  }
+  return url;
+}
+
+function mediaTags(
+  kind: "image" | "video",
+  media: SocialImage | SocialVideo,
+): SocialMetaTag[] {
+  const url = httpsUrl(media.url).href;
+  if (![media.width, media.height].every((size) => Number.isSafeInteger(size) && size > 0)) {
+    throw new Error(`Social ${kind} dimensions must be positive pixel counts`);
+  }
+  const types = kind === "image"
+    ? ["image/png", "image/jpeg", "image/webp"]
+    : ["video/mp4", "video/webm"];
+  if (!types.includes(media.type)) throw new Error(`Unsupported social ${kind} MIME type`);
+  return [
+    { property: `og:${kind}`, content: url },
+    { property: `og:${kind}:secure_url`, content: url },
+    { property: `og:${kind}:type`, content: media.type },
+    { property: `og:${kind}:width`, content: String(media.width) },
+    { property: `og:${kind}:height`, content: String(media.height) },
+  ];
+}
+
+/** Render these tags in the server/static head, never after hydration.
+ * Video metadata advertises an asset; a social client's playback needs its own proof.
+ */
+export function socialMetadata(page: SocialPage): {
+  canonicalUrl: string;
+  tags: SocialMetaTag[];
+} {
+  for (const text of [page.title, page.description, page.image.alt]) {
+    if (!text.trim()) throw new Error("Social title, description and image alt must be nonempty");
+  }
+  const canonical = httpsUrl(page.url);
+  canonical.search = "";
+  canonical.hash = "";
+  const canonicalUrl = canonical.href;
+  const imageUrl = httpsUrl(page.image.url).href;
+  return {
+    canonicalUrl,
+    tags: [
+      { property: "og:type", content: page.type ?? "website" },
+      { property: "og:site_name", content: page.siteName ?? "Tangle" },
+      { property: "og:url", content: canonicalUrl },
+      { property: "og:title", content: page.title },
+      { property: "og:description", content: page.description },
+      ...mediaTags("image", page.image),
+      { property: "og:image:alt", content: page.image.alt },
+      ...(page.video ? mediaTags("video", page.video) : []),
+      { name: "twitter:card", content: "summary_large_image" },
+      { name: "twitter:site", content: "@tangle_network" },
+      { name: "twitter:title", content: page.title },
+      { name: "twitter:description", content: page.description },
+      { name: "twitter:image", content: imageUrl },
+      { name: "twitter:image:alt", content: page.image.alt },
+    ],
+  };
+}