@tuturuuu/utils 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.16.0](https://github.com/tutur3u/platform/compare/utils-v0.15.1...utils-v0.16.0) (2026-07-18)
+
+
+### Features
+
+* **seo:** improve discovery metadata ([a574409](https://github.com/tutur3u/platform/commit/a57440984df45086c4989db07b02d402dd93c828))
+* **seo:** improve discovery metadata ([8e2420d](https://github.com/tutur3u/platform/commit/8e2420d49e7b94c462d92222ea8f239ab92564f6))
+* **seo:** improve page metadata ([0c621cb](https://github.com/tutur3u/platform/commit/0c621cb7fc1253b0a11ea21992503274052c6be0))
+* **seo:** standardize app metadata ([6523d91](https://github.com/tutur3u/platform/commit/6523d91fedf38e19804d10ea3b82890db180bc6f))
+
+
+### Bug Fixes
+
+* **mobile:** preserve bearer auth across satellites ([f890170](https://github.com/tutur3u/platform/commit/f89017044cf3aaaa6a1b15c31c64a81d75cfdab2))
+
+## [0.15.1](https://github.com/tutur3u/platform/compare/utils-v0.15.0...utils-v0.15.1) (2026-07-13)
+
+
+### Bug Fixes
+
+* **contacts:** restore group post mutations ([fe621e4](https://github.com/tutur3u/platform/commit/fe621e4d7e4126f705082cc3e815aafdeebe535a))
+* **security:** prevent clickjacking across apps ([c8ed36e](https://github.com/tutur3u/platform/commit/c8ed36e708c08ebe3b17ee7f6249513644108c48))
+
 ## [0.15.0](https://github.com/tutur3u/platform/compare/utils-v0.14.0...utils-v0.15.0) (2026-07-11)
 
 

package/biome.json

@@ -1,5 +1,5 @@
 {
   "root": false,
-  "$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.4/schema.json",
   "extends": "//"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tuturuuu/utils",
   "license": "MIT",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/tutur3u/platform",
@@ -20,11 +20,11 @@
     "@noble/ciphers": "^2.2.0",
     "@noble/hashes": "^2.2.0",
     "@tanstack/react-query": "^5.101.2",
-    "@tiptap/core": "3.27.3",
-    "@tiptap/react": "3.27.3",
+    "@tiptap/core": "3.27.4",
+    "@tiptap/react": "3.27.4",
     "@tuturuuu/google": "0.0.3",
     "@tuturuuu/icons": "0.0.6",
-    "@tuturuuu/internal-api": "0.17.0",
+    "@tuturuuu/internal-api": "0.19.0",
     "@tuturuuu/supabase": "0.4.0",
     "@upstash/ratelimit": "^2.0.8",
     "@upstash/redis": "^1.38.0",
@@ -32,9 +32,9 @@
     "date-fns": "^4.4.0",
     "dayjs": "^1.11.20",
     "diff": "^9.0.0",
-    "effect": "^3.21.4",
+    "effect": "^3.22.0",
     "moment": "^2.30.1",
-    "next": "^16.3.0-preview.5",
+    "next": "^16.3.0-preview.6",
     "prosemirror-model": "^1.25.11",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
@@ -45,7 +45,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@tuturuuu/types": "0.16.0",
+    "@tuturuuu/types": "0.18.0",
     "@tuturuuu/typescript-config": "0.1.1",
     "@types/diff": "^8.0.0",
     "@types/node": "^26.1.1",
@@ -62,6 +62,7 @@
     "./hooks/*": "./src/hooks/*.ts",
     "./*": "./src/*.ts",
     "./common/scan": "./src/common/scan.tsx",
+    "./common/metadata": "./src/common/metadata.ts",
     "./common/nextjs": "./src/common/nextjs.tsx",
     "./permissions": "./src/permissions.tsx",
     "./editor": "./src/editor/index.ts",

package/src/__tests__/api-proxy-guard.test.ts

@@ -1663,6 +1663,23 @@ describe('guardApiProxyRequest', () => {
     ).toBe(false);
   });
 
+  it('detects bearer credentials that route handlers can authenticate', async () => {
+    const { hasAuthenticatedBearerToken } = await import(
+      '../api-proxy-guard.js'
+    );
+
+    expect(
+      hasAuthenticatedBearerToken(
+        new Headers({ authorization: 'Bearer header.payload.signature' })
+      )
+    ).toBe(true);
+    expect(
+      hasAuthenticatedBearerToken(
+        new Headers({ authorization: 'Bearer malformed-token' })
+      )
+    ).toBe(false);
+  });
+
   it('enforces anonymous IP blocks for cookie-looking browser requests', async () => {
     vi.stubEnv('NODE_ENV', 'production');
     vi.stubEnv('UPSTASH_REDIS_REST_URL', 'https://redis.test');
@@ -1735,35 +1752,35 @@ describe('guardApiProxyRequest', () => {
     );
   });
 
-  it.each([
-    '/api/v1/auth/otp/send',
-    '/api/v1/auth/mobile/send-otp',
-  ])('uses a classroom-friendly OTP send bucket for %s', async (path) => {
-    vi.stubEnv('NODE_ENV', 'production');
-    vi.stubEnv('UPSTASH_REDIS_REST_URL', 'https://redis.test');
-    vi.stubEnv('UPSTASH_REDIS_REST_TOKEN', 'token');
-    mocks.redis.mockReturnValue({});
-    mocks.extractIp.mockReturnValue('1.2.3.4');
-    mocks.isBlocked.mockResolvedValue(null);
-    mocks.limit.mockResolvedValueOnce({
-      success: false,
-      limit: 30,
-      remaining: 0,
-      reset: Date.now() + 15_000,
-    });
+  it.each(['/api/v1/auth/otp/send', '/api/v1/auth/mobile/send-otp'])(
+    'uses a classroom-friendly OTP send bucket for %s',
+    async (path) => {
+      vi.stubEnv('NODE_ENV', 'production');
+      vi.stubEnv('UPSTASH_REDIS_REST_URL', 'https://redis.test');
+      vi.stubEnv('UPSTASH_REDIS_REST_TOKEN', 'token');
+      mocks.redis.mockReturnValue({});
+      mocks.extractIp.mockReturnValue('1.2.3.4');
+      mocks.isBlocked.mockResolvedValue(null);
+      mocks.limit.mockResolvedValueOnce({
+        success: false,
+        limit: 30,
+        remaining: 0,
+        reset: Date.now() + 15_000,
+      });
 
-    const { guardApiProxyRequest, clearApiProxyGuardLimiterCache } =
-      await import('../api-proxy-guard.js');
-    clearApiProxyGuardLimiterCache();
+      const { guardApiProxyRequest, clearApiProxyGuardLimiterCache } =
+        await import('../api-proxy-guard.js');
+      clearApiProxyGuardLimiterCache();
 
-    const response = await guardApiProxyRequest(makeRequest(path, 'POST'), {
-      prefixBase: 'proxy:test:api',
-    });
+      const response = await guardApiProxyRequest(makeRequest(path, 'POST'), {
+        prefixBase: 'proxy:test:api',
+      });
 
-    expect(response?.status).toBe(429);
-    expect(response?.headers.get('X-RateLimit-Limit')).toBe('30');
-    expect(response?.headers.get('X-RateLimit-Policy')).toBe('otp-send');
-  });
+      expect(response?.status).toBe(429);
+      expect(response?.headers.get('X-RateLimit-Limit')).toBe('30');
+      expect(response?.headers.get('X-RateLimit-Policy')).toBe('otp-send');
+    }
+  );
 
   it('uses a classroom-friendly bucket for cross-app return handoffs', async () => {
     vi.stubEnv('NODE_ENV', 'production');

package/src/api-proxy-guard.ts

@@ -763,7 +763,7 @@ function looksLikeWorkspaceApiKey(token: string): boolean {
   return /^ttr_[A-Za-z0-9_-]+$/.test(token);
 }
 
-function hasAuthenticatedBearerToken(headers: Headers): boolean {
+export function hasAuthenticatedBearerToken(headers: Headers): boolean {
   const authHeader = headers.get('authorization');
   if (!authHeader) {
     return false;

package/src/common/metadata.test.ts

@@ -0,0 +1,319 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  createCommonMetadata,
+  createPageMetadata,
+  NO_INDEX_ROBOTS,
+} from './metadata';
+
+const repoRoot = resolve(__dirname, '../../../..');
+
+const config = {
+  description: {
+    en: 'English product description.',
+    vi: 'Mo ta san pham bang tieng Viet.',
+  },
+  indexable: true,
+  keywords: ['team collaboration', 'workflow automation'],
+  name: 'Tuturuuu Test',
+  url: 'https://test.tuturuuu.com',
+};
+
+describe('createCommonMetadata', () => {
+  it('builds localized, indexable product metadata', () => {
+    const metadata = createCommonMetadata({ config, locale: 'vi' });
+
+    expect(metadata.description).toBe('Mo ta san pham bang tieng Viet.');
+    expect(metadata.metadataBase?.toString()).toBe(
+      'https://test.tuturuuu.com/'
+    );
+    expect(metadata.keywords).toEqual([
+      'Tuturuuu Test',
+      'Tuturuuu',
+      'team collaboration',
+      'workflow automation',
+    ]);
+    expect(metadata.robots).toMatchObject({
+      follow: true,
+      index: true,
+    });
+    expect(metadata.openGraph).toMatchObject({
+      alternateLocale: ['en_US'],
+      description: 'Mo ta san pham bang tieng Viet.',
+      locale: 'vi_VN',
+      siteName: 'Tuturuuu Test',
+      title: 'Tuturuuu Test',
+    });
+    expect(metadata.twitter).toMatchObject({
+      card: 'summary_large_image',
+      creator: '@tuturuuu',
+      site: '@tuturuuu',
+    });
+  });
+
+  it('uses valid shared brand assets without advertising a missing manifest', () => {
+    const metadata = createCommonMetadata({ config, locale: 'en' });
+
+    expect(metadata.icons).toEqual({
+      apple: 'https://tuturuuu.com/apple-touch-icon.png',
+      icon: 'https://tuturuuu.com/favicon.ico',
+      shortcut: 'https://tuturuuu.com/favicon-16x16.png',
+    });
+    expect(metadata.manifest).toBeUndefined();
+    expect(metadata.openGraph).toMatchObject({
+      images: [
+        {
+          alt: 'Tuturuuu Test preview',
+          height: 630,
+          url: 'https://tuturuuu.com/media/logos/og-image.jpg',
+          width: 1200,
+        },
+      ],
+      locale: 'en_US',
+    });
+  });
+
+  it('prevents private application surfaces from being indexed', () => {
+    const metadata = createCommonMetadata({
+      config: {
+        ...config,
+        indexable: false,
+      },
+      locale: 'en',
+    });
+
+    expect(metadata.robots).toEqual({
+      follow: false,
+      googleBot: {
+        follow: false,
+        index: false,
+      },
+      index: false,
+    });
+  });
+
+  it('includes a manifest only when the application declares one', () => {
+    const metadata = createCommonMetadata({
+      config: {
+        ...config,
+        manifest: '/manifest.webmanifest',
+      },
+      locale: 'en',
+    });
+
+    expect(metadata.manifest).toBe('/manifest.webmanifest');
+  });
+});
+
+describe('createPageMetadata', () => {
+  it('builds canonical, hreflang, and social metadata for a localized page', () => {
+    const metadata = createPageMetadata({
+      baseUrl: 'https://test.tuturuuu.com',
+      description: 'Plan and automate team workflows.',
+      image: '/media/workflows-og.png',
+      locale: 'vi',
+      pathname: '/products/workflows',
+      title: 'Workflow Automation',
+    });
+
+    expect(metadata.alternates).toEqual({
+      canonical: 'https://test.tuturuuu.com/vi/products/workflows',
+      languages: {
+        'en-US': 'https://test.tuturuuu.com/products/workflows',
+        'vi-VN': 'https://test.tuturuuu.com/vi/products/workflows',
+        'x-default': 'https://test.tuturuuu.com/products/workflows',
+      },
+    });
+    expect(metadata.openGraph).toMatchObject({
+      alternateLocale: ['en_US'],
+      description: 'Plan and automate team workflows.',
+      locale: 'vi_VN',
+      siteName: 'Tuturuuu',
+      title: 'Workflow Automation',
+      url: 'https://test.tuturuuu.com/vi/products/workflows',
+      images: [
+        {
+          alt: 'Workflow Automation',
+          height: 630,
+          url: 'https://test.tuturuuu.com/media/workflows-og.png',
+          width: 1200,
+        },
+      ],
+    });
+    expect(metadata.twitter).toMatchObject({
+      card: 'summary_large_image',
+      creator: '@tuturuuu',
+      site: '@tuturuuu',
+      title: 'Workflow Automation',
+    });
+  });
+
+  it('does not override inherited robots unless page indexing is explicit', () => {
+    const baseConfig = {
+      baseUrl: 'https://test.tuturuuu.com',
+      description: 'Private workspace page.',
+      locale: 'en',
+      pathname: '/workspace',
+      title: 'Workspace',
+    };
+
+    expect(createPageMetadata(baseConfig).robots).toBeUndefined();
+    expect(
+      createPageMetadata({ ...baseConfig, indexable: false }).robots
+    ).toEqual(NO_INDEX_ROBOTS);
+  });
+
+  it('uses the unprefixed English URL configured by the public router', () => {
+    const metadata = createPageMetadata({
+      baseUrl: 'https://test.tuturuuu.com',
+      description: 'The main product landing page.',
+      locale: 'en',
+      pathname: '/',
+      title: 'Tuturuuu',
+    });
+
+    expect(metadata.alternates).toEqual({
+      canonical: 'https://test.tuturuuu.com/',
+      languages: {
+        'en-US': 'https://test.tuturuuu.com/',
+        'vi-VN': 'https://test.tuturuuu.com/vi',
+        'x-default': 'https://test.tuturuuu.com/',
+      },
+    });
+  });
+
+  it('supports apps that never expose locale prefixes', () => {
+    const metadata = createPageMetadata({
+      baseUrl: 'https://tools.tuturuuu.com',
+      description: 'Localized tools on one stable URL.',
+      locale: 'vi',
+      localePrefix: 'never',
+      pathname: '/qr',
+      title: 'QR Code Generator',
+    });
+
+    expect(metadata.alternates).toEqual({
+      canonical: 'https://tools.tuturuuu.com/qr',
+    });
+    expect(metadata.openGraph).toMatchObject({
+      locale: 'vi_VN',
+      url: 'https://tools.tuturuuu.com/qr',
+    });
+  });
+
+  it('supports apps that always expose locale prefixes', () => {
+    const metadata = createPageMetadata({
+      baseUrl: 'https://example.tuturuuu.com',
+      description: 'A prefixed localized page.',
+      locale: 'en',
+      localePrefix: 'always',
+      pathname: '/about',
+      title: 'About',
+    });
+
+    expect(metadata.alternates).toMatchObject({
+      canonical: 'https://example.tuturuuu.com/en/about',
+      languages: {
+        'en-US': 'https://example.tuturuuu.com/en/about',
+        'vi-VN': 'https://example.tuturuuu.com/vi/about',
+      },
+    });
+  });
+});
+
+describe('application metadata coverage', () => {
+  it('keeps every Next.js application on the shared metadata contract', () => {
+    const appsDirectory = resolve(repoRoot, 'apps');
+    const nextApps = readdirSync(appsDirectory, { withFileTypes: true })
+      .filter(
+        (entry) =>
+          entry.isDirectory() &&
+          existsSync(resolve(appsDirectory, entry.name, 'next.config.ts'))
+      )
+      .map((entry) => entry.name)
+      .sort();
+
+    expect(nextApps.length).toBeGreaterThan(0);
+
+    for (const app of nextApps) {
+      const appDirectory = resolve(appsDirectory, app, 'src/app');
+      const localizedLayout = resolve(appDirectory, '[locale]/layout.tsx');
+      const rootLayout = resolve(appDirectory, 'layout.tsx');
+      const layoutPath = existsSync(localizedLayout)
+        ? localizedLayout
+        : rootLayout;
+
+      expect(existsSync(layoutPath), `${app} is missing a root layout`).toBe(
+        true
+      );
+      expect(
+        readFileSync(layoutPath, 'utf8'),
+        `${app} is not using the shared metadata contract`
+      ).toMatch(/(?:create|generate)CommonMetadata/);
+    }
+  });
+
+  it('covers the non-Next public application shells', () => {
+    const tanStackHead = readFileSync(
+      resolve(repoRoot, 'apps/tanstack-web/src/lib/platform/app-shell.ts'),
+      'utf8'
+    );
+    const mobileHead = readFileSync(
+      resolve(repoRoot, 'apps/mobile/web/index.html'),
+      'utf8'
+    );
+    const docsConfig = JSON.parse(
+      readFileSync(resolve(repoRoot, 'apps/docs/docs.json'), 'utf8')
+    ) as { description?: string };
+
+    expect(tanStackHead).toContain('max-image-preview:large');
+    expect(tanStackHead).toContain("name: 'twitter:site'");
+    expect(mobileHead).toContain('name="robots" content="noindex, nofollow"');
+    expect(mobileHead).toContain('property="og:image"');
+    expect(docsConfig.description).toMatch(/Tuturuuu platform/);
+  });
+
+  it('keeps SEO-critical public routes on page-specific metadata', () => {
+    const routeFiles = [
+      'apps/apps/src/app/[locale]/page.tsx',
+      'apps/learn/src/app/[locale]/page.tsx',
+      'apps/teach/src/app/[locale]/page.tsx',
+      'apps/tools/src/app/[locale]/page.tsx',
+      'apps/tools/src/app/[locale]/qr/page.tsx',
+      'apps/tools/src/app/[locale]/random/page.tsx',
+      'apps/storefront/src/app/[locale]/[storeSlug]/page.tsx',
+      'apps/storefront/src/app/[locale]/[storeSlug]/products/[listingId]/page.tsx',
+      'apps/nova/src/app/[locale]/(marketing)/layout.tsx',
+      'apps/nova/src/app/[locale]/(marketing)/learn/layout.tsx',
+    ];
+
+    for (const routeFile of routeFiles) {
+      const source = readFileSync(resolve(repoRoot, routeFile), 'utf8');
+
+      expect(
+        source,
+        `${routeFile} is missing page-specific SEO metadata`
+      ).toMatch(/create(?:Page|NovaPage)Metadata/);
+    }
+
+    const marketingLayouts = readdirSync(
+      resolve(repoRoot, 'apps/web/src/app/[locale]/(marketing)'),
+      { recursive: true, withFileTypes: true }
+    )
+      .filter(
+        (entry) =>
+          entry.isFile() &&
+          entry.name === 'layout.tsx' &&
+          readFileSync(resolve(entry.parentPath, entry.name), 'utf8').includes(
+            'createMarketingMetadata'
+          )
+      )
+      .map((entry) => resolve(entry.parentPath, entry.name));
+
+    expect(marketingLayouts).toHaveLength(34);
+    for (const layoutPath of marketingLayouts) {
+      expect(readFileSync(layoutPath, 'utf8')).toMatch(/pathname:\s*['`]/);
+    }
+  });
+});

package/src/common/metadata.ts

@@ -0,0 +1,265 @@
+import type { Metadata } from 'next';
+import { DEV_MODE } from '../constants';
+
+const TUTURUUU_URL = 'https://tuturuuu.com';
+const DEFAULT_OG_IMAGE = `${TUTURUUU_URL}/media/logos/og-image.jpg`;
+
+export const NO_INDEX_ROBOTS = {
+  index: false,
+  follow: false,
+  googleBot: {
+    index: false,
+    follow: false,
+  },
+} satisfies NonNullable<Metadata['robots']>;
+
+export interface CommonMetadataConfig {
+  name: string;
+  url: string;
+  indexable: boolean;
+  keywords: string[];
+  description: {
+    en: string;
+    vi?: string;
+  };
+  authors?: Metadata['authors'];
+  category?: string;
+  creator?: string;
+  icons?: Metadata['icons'];
+  manifest?: string;
+  ogImage?: string;
+  publisher?: string;
+}
+
+export interface PageMetadataConfig {
+  baseUrl: string;
+  description: string;
+  image?: string;
+  imageAlt?: string;
+  indexable?: boolean;
+  keywords?: string[];
+  locale: string;
+  localePrefix?: 'always' | 'as-needed' | 'never';
+  pathname: string;
+  siteName?: string;
+  socialDescription?: string;
+  socialTitle?: string;
+  title: string;
+}
+
+interface CreateCommonMetadataProps {
+  config: CommonMetadataConfig;
+  locale: string;
+}
+
+interface GenerateCommonMetadataProps {
+  config: CommonMetadataConfig;
+  params: Promise<{
+    locale: string;
+  }>;
+}
+
+interface GeneratePageMetadataProps {
+  config: Omit<PageMetadataConfig, 'locale'>;
+  params: Promise<{
+    locale: string;
+  }>;
+}
+
+function getOpenGraphLocale(locale: string) {
+  return locale === 'vi' ? 'vi_VN' : 'en_US';
+}
+
+function getLocalizedUrl(
+  baseUrl: string,
+  locale: string,
+  pathname: string,
+  localePrefix: NonNullable<PageMetadataConfig['localePrefix']>
+) {
+  const normalizedPathname =
+    pathname === '/' ? '' : `/${pathname.replace(/^\/+|\/+$/g, '')}`;
+  const localizedPrefix =
+    localePrefix === 'never' ||
+    (localePrefix === 'as-needed' && locale === 'en')
+      ? ''
+      : `/${locale}`;
+  const localizedPathname = `${localizedPrefix}${normalizedPathname}` || '/';
+
+  return new URL(localizedPathname, baseUrl).toString();
+}
+
+function getRobotsMetadata(indexable: boolean): Metadata['robots'] {
+  if (!indexable) {
+    return NO_INDEX_ROBOTS;
+  }
+
+  return {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+      'max-image-preview': 'large',
+      'max-snippet': -1,
+      'max-video-preview': -1,
+    },
+  };
+}
+
+export function createCommonMetadata({
+  config,
+  locale,
+}: CreateCommonMetadataProps): Metadata {
+  const description =
+    locale === 'vi' && config.description.vi
+      ? config.description.vi
+      : config.description.en;
+  const ogImage = config.ogImage ?? DEFAULT_OG_IMAGE;
+  const openGraphLocale = getOpenGraphLocale(locale);
+
+  return {
+    applicationName: config.name,
+    title: {
+      default: config.name,
+      template: `${DEV_MODE ? '[DEV] ' : ''}%s | ${config.name}`,
+    },
+    metadataBase: new URL(config.url),
+    description,
+    keywords: [...new Set([config.name, 'Tuturuuu', ...config.keywords])],
+    authors: config.authors ?? [
+      {
+        name: 'Tuturuuu',
+        url: TUTURUUU_URL,
+      },
+    ],
+    creator: config.creator ?? 'Tuturuuu',
+    publisher: config.publisher ?? 'Tuturuuu',
+    category: config.category,
+    referrer: 'origin-when-cross-origin',
+    robots: getRobotsMetadata(config.indexable),
+    appleWebApp: {
+      capable: true,
+      statusBarStyle: 'default',
+      title: config.name,
+    },
+    formatDetection: {
+      address: false,
+      email: false,
+      telephone: false,
+    },
+    openGraph: {
+      type: 'website',
+      locale: openGraphLocale,
+      alternateLocale: [openGraphLocale === 'vi_VN' ? 'en_US' : 'vi_VN'],
+      title: config.name,
+      description,
+      siteName: config.name,
+      images: [
+        {
+          url: ogImage,
+          width: 1200,
+          height: 630,
+          alt: `${config.name} preview`,
+        },
+      ],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: config.name,
+      description,
+      images: [ogImage],
+      creator: '@tuturuuu',
+      site: '@tuturuuu',
+    },
+    icons: config.icons ?? {
+      icon: `${TUTURUUU_URL}/favicon.ico`,
+      shortcut: `${TUTURUUU_URL}/favicon-16x16.png`,
+      apple: `${TUTURUUU_URL}/apple-touch-icon.png`,
+    },
+    manifest: config.manifest,
+  };
+}
+
+export function createPageMetadata({
+  baseUrl,
+  description,
+  image = DEFAULT_OG_IMAGE,
+  imageAlt,
+  indexable,
+  keywords,
+  locale,
+  localePrefix = 'as-needed',
+  pathname,
+  siteName = 'Tuturuuu',
+  title,
+  socialDescription = description,
+  socialTitle = title,
+}: PageMetadataConfig): Metadata {
+  const canonical = getLocalizedUrl(baseUrl, locale, pathname, localePrefix);
+  const englishUrl = getLocalizedUrl(baseUrl, 'en', pathname, localePrefix);
+  const vietnameseUrl = getLocalizedUrl(baseUrl, 'vi', pathname, localePrefix);
+  const openGraphLocale = getOpenGraphLocale(locale);
+  const absoluteImage = new URL(image, baseUrl).toString();
+
+  return {
+    title,
+    description,
+    ...(keywords?.length ? { keywords } : {}),
+    ...(typeof indexable === 'boolean'
+      ? { robots: getRobotsMetadata(indexable) }
+      : {}),
+    alternates: {
+      canonical,
+      ...(localePrefix === 'never'
+        ? {}
+        : {
+            languages: {
+              'en-US': englishUrl,
+              'vi-VN': vietnameseUrl,
+              'x-default': englishUrl,
+            },
+          }),
+    },
+    openGraph: {
+      type: 'website',
+      url: canonical,
+      locale: openGraphLocale,
+      alternateLocale: [openGraphLocale === 'vi_VN' ? 'en_US' : 'vi_VN'],
+      siteName,
+      title: socialTitle,
+      description: socialDescription,
+      images: [
+        {
+          url: absoluteImage,
+          width: 1200,
+          height: 630,
+          alt: imageAlt ?? socialTitle,
+        },
+      ],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: socialTitle,
+      description: socialDescription,
+      images: [absoluteImage],
+      creator: '@tuturuuu',
+      site: '@tuturuuu',
+    },
+  };
+}
+
+export async function generateCommonMetadata({
+  config,
+  params,
+}: GenerateCommonMetadataProps): Promise<Metadata> {
+  const { locale } = await params;
+  return createCommonMetadata({ config, locale });
+}
+
+export async function generatePageMetadata({
+  config,
+  params,
+}: GeneratePageMetadataProps): Promise<Metadata> {
+  const { locale } = await params;
+  return createPageMetadata({ ...config, locale });
+}

package/src/common/nextjs.tsx

@@ -1,91 +1,21 @@
-import type { Metadata, Viewport } from 'next';
+import type { Viewport } from 'next';
 import { Noto_Sans } from 'next/font/google';
-import { DEV_MODE } from '../constants';
+
+export {
+  type CommonMetadataConfig,
+  createCommonMetadata,
+  createPageMetadata,
+  generateCommonMetadata,
+  generatePageMetadata,
+  NO_INDEX_ROBOTS,
+  type PageMetadataConfig,
+} from './metadata';
 
 export const font = Noto_Sans({
   subsets: ['latin', 'vietnamese'],
   display: 'block',
 });
 
-interface MetadataProps {
-  config: {
-    name: string;
-    url: string;
-    ogImage: string;
-    keywords?: string[];
-    description: {
-      en: string;
-      vi?: string;
-    };
-  };
-  params: Promise<{
-    locale: string;
-  }>;
-}
-
-export async function generateCommonMetadata({
-  config,
-  params,
-}: MetadataProps): Promise<Metadata> {
-  const { locale } = await params;
-  const description =
-    locale === 'vi' ? config.description.vi : config.description.en;
-
-  return {
-    applicationName: config.name,
-    title: {
-      default: config.name,
-      template: `${DEV_MODE ? '[DEV] ' : ''} %s | ${config.name}`,
-    },
-    metadataBase: new URL(config.url),
-    description,
-    keywords: config.keywords ?? [
-      'React.js',
-      'Next.js',
-      'Tailwind CSS',
-      'TypeScript',
-      'Biome',
-    ],
-    appleWebApp: {
-      capable: true,
-      statusBarStyle: 'default',
-      title: config.name,
-    },
-    formatDetection: {
-      telephone: false,
-    },
-    openGraph: {
-      type: 'website',
-      locale,
-      url: config.url,
-      title: config.name,
-      description,
-      siteName: config.name,
-      images: [
-        {
-          url: config.ogImage,
-          width: 1200,
-          height: 630,
-          alt: config.name,
-        },
-      ],
-    },
-    twitter: {
-      card: 'summary_large_image',
-      title: config.name,
-      description,
-      images: [config.ogImage],
-      creator: '@tuturuuu',
-    },
-    icons: {
-      icon: '/favicon.ico',
-      shortcut: '/favicon-16x16.png',
-      apple: '/apple-touch-icon.png',
-    },
-    manifest: '/manifest.webmanifest',
-  };
-}
-
 export const viewport: Viewport = {
   width: 'device-width',
   initialScale: 1,

package/src/next-config.test.ts

@@ -1,3 +1,4 @@
+import { tryToParsePath } from 'next/dist/lib/try-to-parse-path';
 import { describe, expect, it } from 'vitest';
 import {
   createTuturuuuNextConfig,
@@ -16,6 +17,7 @@ describe('createTuturuuuNextConfig', () => {
     expect(config.allowedDevOrigins).toContain('tuturuuu.localhost');
     expect(config.cacheComponents).toBe(true);
     expect(config.partialPrefetching).toBe(true);
+    expect(config.experimental?.useTypeScriptCli).toBe(true);
     expect(config.experimental?.turbopackFileSystemCacheForBuild).toBe(true);
     expect(config.experimental?.turbopackRustReactCompiler).toBe(true);
     expect(config.images?.remotePatterns).toEqual(
@@ -40,6 +42,97 @@ describe('createTuturuuuNextConfig', () => {
     });
   });
 
+  it('protects responses from framing by default', async () => {
+    const config = createTuturuuuNextConfig();
+
+    await expect(config.headers?.()).resolves.toEqual([
+      {
+        source:
+          '/:path((?!api/v1/workspaces/[^/]+/external-projects/assets/[^/]+/webgl(?:/|$)).*)',
+        headers: [
+          {
+            key: 'Content-Security-Policy',
+            value: "frame-ancestors 'none'",
+          },
+          {
+            key: 'X-Frame-Options',
+            value: 'DENY',
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('preserves app-specific response headers after shared security headers', async () => {
+    const config = createTuturuuuNextConfig({
+      async headers() {
+        return [
+          {
+            source: '/login',
+            headers: [
+              {
+                key: 'Cache-Control',
+                value: 'public, max-age=0, must-revalidate',
+              },
+              {
+                key: 'X-Robots-Tag',
+                value: 'noindex, nofollow',
+              },
+            ],
+          },
+        ];
+      },
+    });
+
+    const headers = await config.headers?.();
+
+    expect(headers).toHaveLength(2);
+    expect(headers?.[1]).toEqual({
+      source: '/login',
+      headers: [
+        {
+          key: 'Cache-Control',
+          value: 'public, max-age=0, must-revalidate',
+        },
+        {
+          key: 'X-Robots-Tag',
+          value: 'noindex, nofollow',
+        },
+      ],
+    });
+  });
+
+  it('exempts only the sandboxed CMS WebGL asset route from anti-framing headers', async () => {
+    const config = createTuturuuuNextConfig();
+    const [antiFramingRule] = (await config.headers?.()) ?? [];
+    const parsedPath = tryToParsePath(antiFramingRule?.source ?? '');
+
+    expect(parsedPath.error).toBeUndefined();
+    expect(parsedPath.regexStr).toBeDefined();
+
+    const routePattern = new RegExp(parsedPath.regexStr ?? '');
+
+    expect(routePattern.test('/')).toBe(true);
+    expect(routePattern.test('/login')).toBe(true);
+    expect(routePattern.test('/en/workspace')).toBe(true);
+    expect(routePattern.test('/api/billing/workspace/invoice')).toBe(true);
+    expect(
+      routePattern.test(
+        '/api/v1/workspaces/workspace-id/external-projects/assets/asset-id/webgl/index.html'
+      )
+    ).toBe(false);
+    expect(
+      routePattern.test(
+        '/api/v1/workspaces/workspace-id/external-projects/assets/asset-id/webgl'
+      )
+    ).toBe(false);
+    expect(
+      routePattern.test(
+        '/api/v1/workspaces/workspace-id/external-projects/assets/asset-id/webgl-preview'
+      )
+    ).toBe(true);
+  });
+
   it('allows the exact worktree-prefixed Portless host for Next dev assets', () => {
     const originalPortlessUrl = process.env.PORTLESS_URL;
 
@@ -106,6 +199,7 @@ describe('createTuturuuuNextConfig', () => {
         cpus: 2,
         turbopackFileSystemCacheForBuild: false,
         turbopackRustReactCompiler: false,
+        useTypeScriptCli: false,
       },
       typescript: {
         ignoreBuildErrors: false,
@@ -119,6 +213,7 @@ describe('createTuturuuuNextConfig', () => {
     expect(config.experimental?.cpus).toBe(2);
     expect(config.experimental?.turbopackFileSystemCacheForBuild).toBe(false);
     expect(config.experimental?.turbopackRustReactCompiler).toBe(false);
+    expect(config.experimental?.useTypeScriptCli).toBe(true);
     expect(config.typescript?.ignoreBuildErrors).toBe(false);
   });
 

package/src/next-config.ts

@@ -33,6 +33,20 @@ export const TUTURUUU_NEXT_IMAGE_REMOTE_PATTERNS = [
   },
 ] satisfies NextImageRemotePattern[];
 
+const TUTURUUU_ANTI_FRAMING_SOURCE =
+  '/:path((?!api/v1/workspaces/[^/]+/external-projects/assets/[^/]+/webgl(?:/|$)).*)';
+
+const TUTURUUU_ANTI_FRAMING_HEADERS = [
+  {
+    key: 'Content-Security-Policy',
+    value: "frame-ancestors 'none'",
+  },
+  {
+    key: 'X-Frame-Options',
+    value: 'DENY',
+  },
+];
+
 function mergeStringArrays(
   first: readonly string[] | undefined,
   second: readonly string[] | undefined
@@ -98,6 +112,7 @@ export function createTuturuuuNextConfig(config: NextConfig = {}): NextConfig {
     },
     experimental: {
       ...experimentalConfig,
+      useTypeScriptCli: true,
       turbopackFileSystemCacheForBuild:
         experimentalConfig.turbopackFileSystemCacheForBuild ?? true,
       turbopackRustReactCompiler:
@@ -107,6 +122,15 @@ export function createTuturuuuNextConfig(config: NextConfig = {}): NextConfig {
         experimentalConfig.optimizePackageImports
       ),
     },
+    async headers() {
+      return [
+        {
+          source: TUTURUUU_ANTI_FRAMING_SOURCE,
+          headers: TUTURUUU_ANTI_FRAMING_HEADERS,
+        },
+        ...((await config.headers?.()) ?? []),
+      ];
+    },
   };
 }
 

package/src/platform-release.test.ts

@@ -7,7 +7,7 @@ import {
 
 describe('platform release metadata', () => {
   it('uses the centralized shared browser app version', () => {
-    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.21.0'); // x-release-please-version
+    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.23.0'); // x-release-please-version
   });
 
   it('preserves the source timestamp in builtAt and derives a short hash', () => {

package/src/platform-release.ts

@@ -1,6 +1,6 @@
 import { PLATFORM_BUILD_METADATA } from './generated/platform-build-metadata';
 
-export const TUTURUUU_PLATFORM_VERSION = '0.21.0'; // x-release-please-version
+export const TUTURUUU_PLATFORM_VERSION = '0.23.0'; // x-release-please-version
 
 export type PlatformBuildMetadataInput = {
   /** ISO timestamp of the source commit used for the build, not deployment time. */