@flamingo-stack/openframe-frontend-core 0.0.564 → 0.0.565-1861.5100.1

package/src/components/ui/table/index.ts

@@ -8,7 +8,7 @@ export { TableDescriptionCell } from './table-description-cell'
 export { TableEmptyState } from './table-empty-state'
 export { TableHeader } from './table-header'
 export { TableRow } from './table-row'
-export { ROW_HEIGHT_DESKTOP, ROW_HEIGHT_MOBILE, TableCardSkeleton } from './table-skeleton'
+export { COMPACT_ROW_MIN_HEIGHT_PX, ROW_HEIGHT_DESKTOP, ROW_HEIGHT_MOBILE, TableCardSkeleton } from './table-skeleton'
 export { TableTimestampCell } from './table-timestamp-cell'
 export { getHideClasses, isHiddenOnMobile } from './utils'
 

package/src/components/ui/table/table-row.tsx

@@ -5,7 +5,7 @@ import React from 'react'
 import { cn } from '../../../utils/cn'
 import { Checkbox } from '../checkbox'
 import { TableCell } from './table-cell'
-import { ROW_HEIGHT_DESKTOP } from './table-skeleton'
+import { COMPACT_ROW_MIN_HEIGHT, ROW_HEIGHT_DESKTOP } from './table-skeleton'
 import type { TableRowProps } from './types'
 import { getHideClasses } from './utils'
 
@@ -99,7 +99,12 @@ export function TableRow<T = any>({
       <div
         className={cn(
           'relative flex items-center gap-4 px-4',
-          compact ? 'py-2' : cn('py-0', ROW_HEIGHT_DESKTOP),
+          // `compact` rows are content-sized, but every row in a table shows
+          // the same cell shapes, so a MIN height makes the body's height a
+          // function of the row COUNT alone. That is what lets a host reserve
+          // space for a full page and stop the layout jumping between a full
+          // page, a short last page and the skeleton.
+          compact ? cn('py-2', COMPACT_ROW_MIN_HEIGHT) : cn('py-0', ROW_HEIGHT_DESKTOP),
           isLinkMode && 'pointer-events-none'
         )}
       >

package/src/components/ui/table/table-skeleton.tsx

@@ -7,12 +7,26 @@ import type { TableCardSkeletonProps } from './types'
 // INNER row heights: the bordered row card adds 1px top + bottom, so the
 // outer block totals the designed 68px / 80px.
 const ROW_HEIGHT_DESKTOP = 'h-[66px] md:h-[78px]'
+/**
+ * A `compact` row's floor. Compact rows are content-sized (`py-2`), but every
+ * row in one table renders the same cell shapes, so pinning a minimum makes the
+ * body's height a function of the ROW COUNT alone — which is what lets a host
+ * reserve space for a full page and stop the layout jumping between a full
+ * page, a short last page and the skeleton. The skeleton uses it too, so the
+ * loading state is exactly as tall as the rows that replace it.
+ */
+const COMPACT_ROW_MIN_HEIGHT = 'min-h-[56px]'
+/** The same 56, as a number, for hosts reserving `rows x height` of space.
+ *  A LITERAL class above and a literal number here: an interpolated Tailwind
+ *  class is invisible to the scanner and is never generated. */
+const COMPACT_ROW_MIN_HEIGHT_PX = 56
 const ROW_HEIGHT_MOBILE = 'h-[66px]'
 
 /** @deprecated Use `DataTableSkeleton` from `data-table` instead. */
 export function TableCardSkeleton({
   columns,
   rows = 10,
+  compact = false,
   hasActions = false,
   hasChevron = false,
   className,
@@ -33,9 +47,12 @@ export function TableCardSkeleton({
           )}
         >
           {/* Desktop Skeleton */}
+          {/* Matches the ROW it stands in for: a compact row is content-sized
+              with a floor, a normal row is a fixed height. Using the taller of
+              the two here made every compact table jump on its first paint. */}
           <div className={cn(
-            'hidden md:flex items-center gap-4 px-4 py-0',
-            ROW_HEIGHT_DESKTOP,
+            'hidden md:flex items-center gap-4 px-4',
+            compact ? cn('py-2', COMPACT_ROW_MIN_HEIGHT) : cn('py-0', ROW_HEIGHT_DESKTOP),
             rowClassName
           )}>
             {columns.map((column) => (
@@ -94,4 +111,4 @@ export function TableCardSkeleton({
 }
 
 /** @deprecated */
-export { ROW_HEIGHT_DESKTOP, ROW_HEIGHT_MOBILE }
+export { ROW_HEIGHT_DESKTOP, ROW_HEIGHT_MOBILE, COMPACT_ROW_MIN_HEIGHT, COMPACT_ROW_MIN_HEIGHT_PX }

package/src/components/ui/table/table.tsx

@@ -250,6 +250,7 @@ export function Table<T = any>({
           <TableCardSkeleton
             columns={columns}
             rows={skeletonRows}
+            compact={compact}
             hasActions={Boolean(rowActions) && rowActions!.length > 0}
             hasChevron={Boolean(rowHref)}
           />

package/src/components/ui/table/types.ts

@@ -240,6 +240,8 @@ export interface TableCellProps {
 export interface TableCardSkeletonProps {
   columns: TableColumn[]
   rows?: number // Number of skeleton rows to display (default: 10)
+  /** Match a `compact` table's row height, so the first paint does not jump. */
+  compact?: boolean
   hasActions?: boolean
   hasChevron?: boolean
   className?: string

package/src/types/department.ts

@@ -0,0 +1,44 @@
+/**
+ * Departments — THE single source of truth for the org's department
+ * vocabulary.
+ *
+ * The `departments` table is populated from Google Workspace (the org chart)
+ * by the hub's Google sync, which auto-creates a row the first time it sees a
+ * new department name. `profiles.department_id` is an FK to it; there is no
+ * free-text department column and no enum anywhere in code — every consumer
+ * reads the row (or the embedded `DepartmentRef`) and every picker lists the
+ * ACTIVE rows ordered by `display_order`.
+ *
+ * Hub owner module: `lib/data/department-utils.ts`.
+ */
+
+export interface Department {
+  id: string
+  name: string
+  slug: string
+  description?: string | null
+  parent_department_id?: string | null
+  display_order: number
+  is_active: boolean
+}
+
+/** The embedded shape a reader gets through the `department:departments(…)` PostgREST embed. */
+export type DepartmentRef = Pick<Department, 'id' | 'name' | 'slug'> & {
+  display_order?: number
+}
+
+/** `GET /api/admin/departments?counts=…` row — a department plus how many profiles carry it. */
+export interface DepartmentSummary {
+  id: string
+  name: string
+  slug: string
+  count: number
+}
+
+/** Population a department count is taken over. */
+/**
+ * Populations the department count endpoint supports. The hub's runtime
+ * allowlist (`DEPARTMENT_COUNT_POPULATIONS` in lib/data/department-constants.ts)
+ * is the value form of this union — keep the two in step.
+ */
+export type DepartmentCountPopulation = 'directory' | 'scored'

package/src/types/design-doc.ts

@@ -0,0 +1,295 @@
+// Design Doc Types (product-hub)
+// Mirrors product-release.ts — entity + child tables + create/update/filter shapes.
+//
+// Participant sections are keyed by the employee DEPARTMENT (FK to the ONE
+// `departments` table — see department.ts); there is no function enum.
+// Completion-gate math and status transitions live in the hub's
+// `lib/utils/design-doc-gate.ts` (isomorphic, shared by server + client).
+
+import type { EntityAuthor } from './entity-author'
+import type { DeliveryItem } from './delivery'
+import type { RoadmapItem } from '../components/chat/types/entities/roadmap-item'
+import type { DepartmentRef } from './department'
+import type { EmployeeDirectoryRow } from './employee'
+
+// ---------------------------------------------------------------------------
+// Value vocabularies — TYPES ONLY.
+//
+// The runtime lists live ONCE, in the hub's `lib/utils/design-doc-gate.ts`,
+// beside the labels and badge colors that make them useful; that module pins
+// each tuple against the union here at compile time, so the two cannot drift.
+// Declaring `as const` arrays here as well would ship a second copy of every
+// vocabulary that nothing reads — the copy a future contributor edits expecting
+// an effect.
+// ---------------------------------------------------------------------------
+
+export type DesignDocStatus = 'draft' | 'in_review' | 'approved' | 'building' | 'shipped' | 'abandoned'
+
+export type DesignDocTier = 'S' | 'M' | 'L'
+
+export type DesignDocParticipantStatus = 'pending' | 'in_progress' | 'completed' | 'blocked'
+
+export type DesignDocCommentType = 'blocking' | 'suggestion' | 'question' | 'note'
+
+export type DesignDocCommentStatus = 'open' | 'resolved' | 'declined'
+
+export type DesignDocLinkType = 'roadmap_task' | 'figma' | 'claude_artifact' | 'claude_design' | 'brief' | 'other'
+
+export type DesignDocMediaType = 'image' | 'video' | 'screenshot' | 'demo'
+
+// ---------------------------------------------------------------------------
+// Rows (as returned by the hub DAL — hydrated)
+// ---------------------------------------------------------------------------
+
+/**
+ * The profile identity the DAL embeds on participants / comment authors — THE
+ * shared person projection, not a second declaration of it. `email` rides the
+ * detail payload only and is stripped from lists.
+ */
+export type DesignDocPerson = EmployeeDirectoryRow
+
+export interface DesignDocClickUpTask {
+  id: number
+  doc_id: number
+  participant_id: number | null
+  clickup_task_id: string
+  display_order: number | null
+  created_at: string
+  /** Hydrated from the `clickup_tasks` mirror (never the live API). `undefined` = not in the mirror. */
+  task?: DeliveryItem
+}
+
+export interface DesignDocLink {
+  id: number
+  doc_id: number
+  link_type: DesignDocLinkType
+  url: string | null
+  clickup_task_id: string | null
+  title: string | null
+  display_order: number | null
+  created_at: string
+  /**
+   * A `roadmap_task` link, hydrated from the mirror as the ROADMAP item it is —
+   * so it renders with the roadmap card, the same as `/roadmap` and the chat.
+   * `undefined` = the mirror has not seen that id. (Section tasks are a
+   * different entity and carry `DeliveryItem` on `DesignDocClickUpTask`.)
+   */
+  roadmap?: RoadmapItem
+}
+
+export interface DesignDocMedia {
+  id: number
+  doc_id: number
+  participant_id: number | null
+  media_type: DesignDocMediaType
+  media_url: string
+  title: string | null
+  description: string | null
+  display_order: number | null
+  created_at: string
+  created_by: string | null
+}
+
+/**
+ * A comment. ROOT comments (`parent_comment_id === null`) carry `comment_type`
+ * + `status` and gate approval when `blocking` + `open`; REPLIES carry neither
+ * (single-level threads — a reply to a reply is re-parented to the root).
+ */
+export interface DesignDocComment {
+  id: number
+  doc_id: number
+  participant_id: number | null
+  parent_comment_id: number | null
+  author_id: string | null
+  comment_type: DesignDocCommentType | null
+  title: string | null
+  body: string
+  status: DesignDocCommentStatus | null
+  resolved_at: string | null
+  created_at: string
+  author?: DesignDocPerson | null
+  /** Threaded by the DAL; always `[]` on replies. */
+  replies: DesignDocComment[]
+}
+
+export interface DesignDocParticipant {
+  id: number
+  doc_id: number
+  department_id: string
+  department: DepartmentRef
+  assignee_id: string | null
+  assignee?: DesignDocPerson | null
+  status: DesignDocParticipantStatus
+  content: string | null
+  completed_at: string | null
+  display_order: number | null
+  created_at: string
+  updated_at: string
+  tasks: DesignDocClickUpTask[]
+  media: DesignDocMedia[]
+  /** Section-scoped root comments (threaded). */
+  comments: DesignDocComment[]
+}
+
+export interface DesignDocCompletion {
+  total: number
+  completed: number
+  blocked: number
+  openBlocking: number
+  isComplete: boolean
+  waitingOn: Array<{
+    participantId: number
+    department: DepartmentRef
+    assigneeName: string | null
+    status: DesignDocParticipantStatus
+  }>
+}
+
+/** R13 — what the signed-in viewer still owes on one doc. */
+export interface DesignDocMyOpenWork {
+  /** One person may own several department sections on the same doc. */
+  participants: Array<{ id: number; department: DepartmentRef; status: DesignDocParticipantStatus }>
+  openTasks: DeliveryItem[]
+}
+
+export interface DesignDoc {
+  id: number
+  title: string
+  slug: string
+  tier: DesignDocTier
+  summary: string | null
+  content: string | null
+  status: DesignDocStatus
+  author_id: string | null
+  /**
+   * EVERYONE who has handed the DRI role away on this doc (appended, never
+   * overwritten). The third-party break-glass excludes all of them: a DRI who
+   * also holds management could otherwise vacate the seat, act as a "third
+   * party" on their own doc and approve it alone — and with a single scalar,
+   * simply hand the seat on twice to erase the memory of their own vacating.
+   */
+  dri_vacated_by: string[]
+  approved_at: string | null
+  created_at: string
+  updated_at: string
+  /** DRI, hydrated via the shared author hydrator. */
+  author?: EntityAuthor
+  participants: DesignDocParticipant[]
+  links: DesignDocLink[]
+  /** Doc-level comments only (participant-scoped comments ride on their participant). */
+  comments: DesignDocComment[]
+  completion: DesignDocCompletion
+  my_open_work?: DesignDocMyOpenWork
+}
+
+// ---------------------------------------------------------------------------
+// Write shapes
+// ---------------------------------------------------------------------------
+
+export interface DesignDocLinkInput {
+  link_type: DesignDocLinkType
+  url?: string | null
+  clickup_task_id?: string | null
+  title?: string | null
+  display_order?: number
+}
+
+export interface DesignDocClickUpTaskInput {
+  clickup_task_id: string
+  display_order?: number
+}
+
+export interface DesignDocMediaInput {
+  media_type: DesignDocMediaType
+  media_url: string
+  title?: string | null
+  description?: string | null
+  display_order?: number
+}
+
+export interface CreateDesignDocParticipantInput {
+  /** Defaults to the assignee's profile department when omitted. */
+  department_id?: string
+  assignee_id: string
+}
+
+/** Wizard payload (POST /api/admin/design-docs). */
+export interface CreateDesignDocData {
+  title: string
+  slug: string
+  tier: DesignDocTier
+  summary?: string | null
+  /** Spec markdown (Why / What / How); the create screen carries the same body editor as edit. */
+  content?: string | null
+  /** DRI; defaults to the caller. */
+  author_id?: string | null
+  participants: CreateDesignDocParticipantInput[]
+  links: DesignDocLinkInput[]
+}
+
+/**
+ * Doc-level allowlist (PUT). `status` and `participants` are NOT here — status
+ * only moves through PATCH (the gate), participants only through their routes.
+ */
+export interface UpdateDesignDocData {
+  title?: string
+  slug?: string
+  tier?: DesignDocTier
+  summary?: string | null
+  content?: string | null
+  author_id?: string | null
+  links?: DesignDocLinkInput[]
+  /** OCC token — the `updated_at` the editor seeded from; mismatch → 409. */
+  expected_updated_at?: string
+}
+
+export interface UpdateDesignDocParticipantData {
+  content?: string | null
+  status?: DesignDocParticipantStatus
+  assignee_id?: string | null
+  department_id?: string
+  clickup_tasks?: DesignDocClickUpTaskInput[]
+  media?: DesignDocMediaInput[]
+  expected_updated_at?: string
+}
+
+export interface AddDesignDocParticipantData {
+  /** Defaults to the assignee's profile department when omitted. */
+  department_id?: string
+  assignee_id: string
+}
+
+export interface AddDesignDocCommentData {
+  participant_id?: number | null
+  /** Set for a reply; the DAL re-parents replies-of-replies to the root. */
+  parent_comment_id?: number | null
+  /** Required on root comments, ignored on replies. */
+  comment_type?: DesignDocCommentType
+  title?: string | null
+  body: string
+}
+
+export interface DesignDocFilters {
+  status?: string
+  search?: string
+  mine?: 'open'
+  limit?: number
+  offset?: number
+}
+
+export interface DesignDocListResponse {
+  data: DesignDoc[]
+  count: number
+  /** Server-computed status facet counts (how-i-work feed convention). */
+  facets: { status: Record<string, number> }
+}
+
+export interface DesignDocStats {
+  total: number
+  draft: number
+  in_review: number
+  approved: number
+  building: number
+  waiting_on_me_docs: number
+  waiting_on_me_tasks: number
+}

package/src/types/employee.ts

@@ -1,7 +1,31 @@
+import type { DepartmentRef } from './department';
+
+/**
+ * THE person projection every people picker and person embed speaks.
+ *
+ * One shape, because it is one wire payload: the employee-directory endpoints
+ * return it, `EmployeeSelector` renders it, and the design-doc DAL embeds it as
+ * a DRI / section owner / comment author. Everything past `full_name` is
+ * optional because the list payloads project fewer columns than the detail ones
+ * — a narrower reader `Pick<>`s from here rather than re-declaring the fields.
+ */
+export interface EmployeeDirectoryRow {
+  id: string;
+  full_name: string | null;
+  email?: string | null;
+  avatar_url?: string | null;
+  job_title?: string | null;
+  /** FK to the ONE `departments` table; `department` is the embedded row. */
+  department_id?: string | null;
+  department?: DepartmentRef | null;
+}
+
 export interface Employee {
   id: string;
   full_name: string;
-  department: string;
+  /** FK to the ONE `departments` table; `department` is the embedded row. */
+  department_id: string | null;
+  department: DepartmentRef | null;
   avatar_url: string;
   role: string;
   job_title: string;
@@ -16,7 +40,8 @@ export interface EmployeeResponse {
 
 export interface EmployeeProfileData {
   full_name: string;
-  department: string;
+  department_id: string | null;
+  department: DepartmentRef | null;
   avatar_url: string;
   role: string;
   job_title: string;

package/src/types/index.ts

@@ -28,11 +28,13 @@ export * from './customer-interview-ai.types'
 export * from './luma'
 export * from './product-release'
 export * from './delivery'
+export * from './design-doc'
 export * from './vendor'
 export * from './vendor-links'
 export * from './video-processing'
 
 // User and profile types
+export * from './department'
 export * from './employee'
 export * from './profile'
 export * from './team'

package/src/types/marketing.ts

@@ -350,6 +350,7 @@ export type ContentSourceType =
   | 'what_i_shipped'      // What I Shipped employee check-ins (lives on people-hub)
   | 'how_i_work'          // How I Work employee AI-workflow sessions (lives on people-hub)
   | 'faq'                 // FAQ Q&A pair (single-page /faqs index; deep-link by category anchor)
+  | 'design_doc'          // Internal design docs (product-hub admin; preview route only, no public page)
   | 'from_scratch';
 
 export type URLInjectionPreference = 'none' | 'in_post' | 'as_comment';

package/src/types/profile.ts

@@ -1,5 +1,7 @@
 // Profile system TypeScript interfaces for OpenMSP
 
+import type { DepartmentRef } from './department'
+
 export interface ProfileResponse {
   id: string;
   name: string;
@@ -14,7 +16,7 @@ export interface ProfileResponse {
   jobTitle: string | null;
   isCommunityMember: boolean;
   lastSignIn: string | null;
-  department: string | null;
+  department: DepartmentRef | null;
   employeeId: string | null;
 }
 

package/src/types/team.ts

@@ -1,3 +1,5 @@
+import type { DepartmentRef } from './department';
+
 export interface TeamMember {
   id: string;
   employee_id: string;
@@ -9,7 +11,9 @@ export interface TeamMember {
   phone?: string;
   role?: string;
   title?: string;
+  /** Display name of the department (presentational shape); `department_id` is the FK. */
   department?: string;
+  department_id?: string | null;
   team?: string;
   manager_id?: string;
   profile_image_url?: string;
@@ -32,8 +36,20 @@ export interface TeamMember {
 }
 
 export interface TeamSection {
+  /**
+   * The BUCKET key this section was grouped under — the React key, and the one
+   * value guaranteed unique across sections. `department_id` is not: a profile
+   * whose `department_id` points at a row the embed could not resolve lands in
+   * the same "Other" section as the genuinely department-less, and both would
+   * render under the same fallback key.
+   */
+  key: string;
   title: string;
+  /** Department display name. */
   department: string;
+  department_id: string | null;
+  /** `departments.display_order` — sections sort by it (no name sentinels). */
+  display_order: number;
   description: string;
   members: TeamMember[];
 }
@@ -45,5 +61,5 @@ export interface TeamData {
 
 export interface GetTeamOptions {
   includeInactive?: boolean;
-  department?: string;
+  departmentId?: string;
 } 

package/src/types/user.ts

@@ -2,6 +2,8 @@
  * Types related to users
  */
 
+import type { DepartmentRef } from './department'
+
 /**
  * User profile
  */
@@ -14,7 +16,8 @@ export type UserProfile = {
   company: string | null
   bio: string | null
   employee_id: string | null
-  department: string | null
+  department_id: string | null
+  department: DepartmentRef | null
   role: 'user' | 'super_admin'
   msp_id: string | null
   created_at: string

package/src/utils/__tests__/claude-embed-url.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest'
+import { toClaudeEmbedUrl } from '../embed-url-converters'
+
+/**
+ * The Claude counterpart of `toFigmaEmbedUrl`, and the newest url-trust
+ * boundary in the markdown pipeline: whatever it returns is put in an iframe
+ * `src`, so "not a published claude.ai artifact" must be `null`, always.
+ */
+describe('toClaudeEmbedUrl', () => {
+  it('normalises every shape of a PUBLISHED artifact url to its embed route', () => {
+    const embed = 'https://claude.ai/public/artifacts/abc-123/embed'
+    expect(toClaudeEmbedUrl('https://claude.ai/public/artifacts/abc-123')).toBe(embed)
+    expect(toClaudeEmbedUrl('https://claude.ai/public/artifacts/abc-123/')).toBe(embed)
+    // The url Anthropic's own "Get embed code" hands the author — the likeliest
+    // paste of all, and it must not be treated as un-embeddable.
+    expect(toClaudeEmbedUrl('https://claude.ai/public/artifacts/abc-123/embed')).toBe(embed)
+    expect(toClaudeEmbedUrl('https://claude.ai/public/artifacts/abc-123/embed/')).toBe(embed)
+    // claude.site short links (and their embed form) 308 to the same artifact.
+    expect(toClaudeEmbedUrl('https://claude.site/artifacts/abc-123')).toBe(embed)
+    expect(toClaudeEmbedUrl('https://claude.site/artifacts/abc-123/embed')).toBe(embed)
+    expect(toClaudeEmbedUrl('https://CLAUDE.AI/public/artifacts/abc-123')).toBe(embed)
+    // Query and fragment are the artifact's, not ours: the embed route is built
+    // from the id alone.
+    expect(toClaudeEmbedUrl('https://claude.ai/public/artifacts/abc-123?x=1#y')).toBe(embed)
+  })
+
+  it('refuses everything that is not a published artifact, and never throws', () => {
+    // A Claude CODE artifact has no embeddable route at all.
+    expect(toClaudeEmbedUrl('https://claude.ai/code/artifact/abc-123')).toBeNull()
+    expect(toClaudeEmbedUrl('https://claude.ai/design/abc-123')).toBeNull()
+    // Host must BE claude.ai/claude.site — not a prefix, a subdomain or userinfo.
+    expect(toClaudeEmbedUrl('https://claude.ai.evil.com/public/artifacts/abc')).toBeNull()
+    expect(toClaudeEmbedUrl('https://evil.com/public/artifacts/abc')).toBeNull()
+    expect(toClaudeEmbedUrl('https://evil.com/?u=https://claude.ai/public/artifacts/abc')).toBeNull()
+    expect(toClaudeEmbedUrl('javascript:alert(1)')).toBeNull()
+    expect(toClaudeEmbedUrl('//claude.ai/public/artifacts/abc')).toBeNull()
+    expect(toClaudeEmbedUrl('not a url')).toBeNull()
+    expect(toClaudeEmbedUrl('')).toBeNull()
+    expect(toClaudeEmbedUrl(null)).toBeNull()
+    expect(toClaudeEmbedUrl(undefined)).toBeNull()
+  })
+})

package/src/utils/embed-url-converters.ts

@@ -75,3 +75,35 @@ export function toFigmaOriginalUrl(url: string): string {
   }
   return url.replace(/\?.*$/, '')
 }
+
+/**
+ * The EMBED url for a published Claude artifact, or `null` when the link is not
+ * one we can frame — the Claude counterpart of `toFigmaEmbedUrl`.
+ *
+ * claude.ai serves `frame-ancestors 'self'` on the artifact page itself, but a
+ * PUBLISHED artifact also has an `/embed` route whose `frame-ancestors` carries
+ * the domains its author allow-listed under "Get embed code → Allowed domains".
+ * That is Anthropic's supported way to put an artifact on another site, so that
+ * is what the iframe points at.
+ *
+ * Returns `null` for everything else, including a Claude CODE url
+ * (`claude.ai/code/artifact/…`), whose Share dialog exposes no Embed settings
+ * and whose `/embed` path answers `frame-ancestors 'self'` (verified against
+ * real artifacts, 2026-08). A trailing `/embed` is accepted because that is the
+ * url "Get embed code" hands the author.
+ */
+export function toClaudeEmbedUrl(url: string | null | undefined): string | null {
+  if (!url) return null
+  try {
+    const u = new URL(url)
+    const host = u.hostname.toLowerCase()
+    // `claude.site/artifacts/<id>` 308-redirects to the claude.ai public url.
+    const publicId =
+      (host === 'claude.ai' && /^\/public\/artifacts\/([\w-]+)(?:\/embed)?\/?$/.exec(u.pathname)?.[1]) ||
+      (host === 'claude.site' && /^\/artifacts\/([\w-]+)(?:\/embed)?\/?$/.exec(u.pathname)?.[1]) ||
+      null
+    return publicId ? `https://claude.ai/public/artifacts/${publicId}/embed` : null
+  } catch {
+    return null
+  }
+}