@tangle-network/brand 1.26.1 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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
+
+- 916d254: Scope GTM design drift to application UI by excluding its customer ad-renderer assets. Add owning-surface exclusions without changing drift baselines or allowing consumer overrides.
+
 ## 1.26.1
 
 ### 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/bin/tangle-drift.mjs

@@ -34,7 +34,8 @@ export const SURFACES = {
   sandbox: { repo: "tangle-network/agent-container", roots: ["products/sandbox/web"] },
   platform: { repo: "tangle-network/agent-container", roots: ["products/platform/web"] },
   intelligence: { repo: "tangle-network/agent-container", roots: ["products/intelligence/web"] },
-  gtm: { repo: "tangle-network/gtm-agent", roots: [""] },
+  // These raw renderer assets run only inside customer ad HTML, never the app UI.
+  gtm: { repo: "tangle-network/gtm-agent", roots: [""], exclude: [":!src/lib/.server/sandbox/creative/*"] },
   tax: { repo: "tangle-network/tax-agent", roots: ["apps/web"] },
   legal: { repo: "tangle-network/legal-agent", roots: [""] },
   insurance: { repo: "tangle-network/insurance-agent", roots: [""] },
@@ -213,7 +214,7 @@ export function grepMatches(source, roots, pattern, exts) {
   const args = ["grep", "-I", "-P", "-n", "-o", "--null", "-e", pattern];
   if (source.rev) args.push(source.rev);
   else args.push("--untracked");
-  args.push("--", ...pathspecs(roots, exts), ...EXCLUDE);
+  args.push("--", ...pathspecs(roots, exts), ...EXCLUDE, ...(source.exclude ?? []));
   const prefix = source.rev ? `${source.rev}:` : "";
   const out = git(source.dir, args, { allowExit1: true });
   const rows = [];
@@ -230,7 +231,7 @@ function grepFiles(source, pattern, specs) {
   const args = ["grep", "-I", "-P", "-l", "--null", "-e", pattern];
   if (source.rev) args.push(source.rev);
   else args.push("--untracked");
-  args.push("--", ...specs, ...EXCLUDE);
+  args.push("--", ...specs, ...EXCLUDE, ...(source.exclude ?? []));
   const prefix = source.rev ? `${source.rev}:` : "";
   return git(source.dir, args, { allowExit1: true }).split("\0").filter(Boolean)
     .map((f) => (f.startsWith(prefix) ? f.slice(prefix.length) : f).trim()).filter(Boolean);
@@ -372,14 +373,15 @@ function pkgVersions(source, roots) {
 
 /** Measure one surface from `source`. `matches` holds the raw gated matches for reporting. */
 export function measure(surface, source) {
-  const { roots, extraExt } = SURFACES[surface];
+  const { roots, extraExt, exclude = [] } = SURFACES[surface];
+  source = { ...source, exclude };
   const files = listFiles(source, roots);
   const srcRe = extraExt ? /\.(tsx|jsx|astro|vue|svelte|js|html)$/ : /\.(tsx|jsx|astro|vue|svelte)$/;
   const tsxFiles = files.filter((f) => srcRe.test(f) && !/node_modules|test|spec|stories|fixtures|dist\//.test(f)).length;
   const cssFiles = files.filter((f) => f.endsWith(".css") && !f.includes("node_modules") && !f.includes("dist/")).length;
 
   const matches = {};
-  const row = { repo: SURFACES[surface].repo, roots, branch: source.branch ?? null, head: source.head ?? null,
+  const row = { repo: SURFACES[surface].repo, roots, exclude, branch: source.branch ?? null, head: source.head ?? null,
     tsx_files: tsxFiles, css_files: cssFiles, versions: pkgVersions(source, roots), importing_files: {} };
   for (const pkg of SHARED) {
     const escaped = pkg.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");

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.1",
+  "version": "1.27.0",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,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 },
+    ],
+  };
+}