@utopia-studio-design/design-system-cli 0.4.0 → 0.5.0

package/README.md

@@ -7,7 +7,13 @@ npm install -D @utopia-studio-design/design-system-cli
 npx utopia-ds init . --theme utopia-default --yes
 npx utopia-ds search "Arabic data table" --json
 npx utopia-ds component DataTable --json
+npx utopia-ds registry --list --json
+npx utopia-ds layout validate ./dashboard-layout.json --json
+npx utopia-ds layout serialize ./dashboard-layout.json
+npx utopia-ds block interaction-workbench --copy ./src/interaction-workbench
 npx utopia-ds template template-saas-solution-homepage --copy ./saas-website
+npx utopia-ds template template-interaction-lab --copy ./interaction-lab
+npx utopia-ds template template-dashboard-composer --copy ./dashboard-composer
 npx utopia-ds template template-saas-solution-homepage --theme dextrum --copy ./dextrum-website
 npx utopia-ds template validate ./my-community-template
 npx utopia-ds template submit ./my-community-template
@@ -17,3 +23,20 @@ npx utopia-ds mcp
 ```
 
 Programmatic consumers can import `@utopia-studio-design/design-system-cli/api`.
+The Ceramic Composition Registry and versioned Layout JSON are the source of
+truth for agent and Studio dashboard composition. The Dashboard Composer's
+optional Puck adapter consumes this API, but it does not define Ceramic blocks
+or styling.
+
+To run the generated Dashboard Composer as a standalone project:
+
+```sh
+cd dashboard-composer
+npm install
+npm run dev
+```
+
+Use `npm run build` before deployment. The generated project pins a compatible
+Ceramic package range and splits the optional Puck editor dependencies into
+separate production chunks; the validated Layout JSON and registry renderer
+remain usable without opening the visual editor.

package/bin/utopia-ds-mcp.mjs

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
 import {
-  capabilityManifest, getComponent, getDoc, getMotionProfile, getTemplate, getTheme,
-  listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, repositoryDoctor, search,
+  capabilityManifest, getBlock, getBlockDefinition, getComponent, getDoc, getMotionProfile, getTemplate, getTheme,
+  listBlockDefinitions, listBlocks, listComponents, listDocs, listMotionProfiles, listTemplates, listThemes,
+  repositoryDoctor, search, validateAgentMutation, validateLayout,
 } from '../lib/api.mjs'
 
 const tools = [
   ['search', 'Search components, docs, templates, themes, and motion profiles.', { query: { type: 'string' } }, ({ query }) => search(query)],
   ['list_components', 'List every Ceramic component contract.', {}, () => listComponents()],
   ['get_component', 'Get one component including imports, tokens, usage, and Arabic rules.', { name: { type: 'string' } }, ({ name }) => getComponent(name)],
+  ['list_block_definitions', 'List Ceramic registry definitions for agent and editor composition.', {}, () => listBlockDefinitions()],
+  ['get_block_definition', 'Get one Ceramic block definition including props, layout, states, and agent permissions.', { id: { type: 'string' } }, ({ id }) => getBlockDefinition(id)],
+  ['validate_layout', 'Validate a versioned Ceramic Layout JSON document without coercion.', { document: { type: 'object' } }, ({ document }) => validateLayout(document)],
+  ['validate_agent_layout_mutation', 'Validate an agent-authored layout change against locks and permissions.', { current: { type: 'object' }, next: { type: 'object' } }, ({ current, next }) => validateAgentMutation(current, next)],
+  ['list_blocks', 'List copyable Ceramic interaction blocks.', {}, () => listBlocks()],
+  ['get_block', 'Get a block contract and copyable bundle metadata.', { id: { type: 'string' } }, ({ id }) => getBlock(id)],
   ['list_templates', 'List Ceramic starter templates.', {}, () => listTemplates()],
   ['get_template', 'Get a template contract and sections.', { id: { type: 'string' } }, ({ id }) => getTemplate(id)],
   ['list_themes', 'List themes that implement the semantic contract.', {}, () => listThemes()],

package/bin/utopia-ds.mjs

@@ -3,10 +3,12 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, wri
 import { dirname, join, resolve } from 'node:path'
 import { spawn } from 'node:child_process'
 import {
-  capabilityManifest, envelope, getComponent, getDoc, getMotionProfile, getTemplate, getTheme,
-  listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, mcpLaunch, repositoryDoctor, search,
+  capabilityManifest, envelope, getBlock, getBlockDefinition, getComponent, getDoc, getMotionProfile, getTemplate, getTheme,
+  listBlockDefinitions, listBlocks, listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, mcpLaunch,
+  repositoryDoctor, search, serializeLayout, validateLayout,
 } from '../lib/api.mjs'
 import { createTemplateSubmissionUrl, validateTemplateSubmission } from '../lib/template-submission.mjs'
+import { installCliTelemetry } from '../lib/telemetry.mjs'
 
 const args = process.argv.slice(2)
 const command = args.find((arg) => !arg.startsWith('--')) ?? 'help'
@@ -15,6 +17,16 @@ const optionsWithValues = new Set(['--copy', '--theme'])
 const values = commandIndex >= 0 ? positionalValues(args.slice(commandIndex + 1)) : []
 const json = args.includes('--json')
 const dense = args.includes('--dense')
+const cliPackageMetadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const cliVersion = cliPackageMetadata.version
+const designSystemVersion = cliPackageMetadata.ceramic.designSystem
+let telemetryErrorCode
+
+installCliTelemetry({
+  command,
+  packageVersion: cliVersion,
+  getErrorCode: () => telemetryErrorCode,
+})
 
 function positionalValues(input) {
   const positionals = []
@@ -36,6 +48,7 @@ function output(type, data, format = null) {
 }
 
 function fail(message, code = 'ERR_INPUT', suggestions = []) {
+  telemetryErrorCode = code
   if (json) console.error(JSON.stringify({ apiVersion: 1, error: message, code, suggestions }, null, 2))
   else console.error(message)
   process.exitCode = 1
@@ -61,6 +74,10 @@ Commands:
   init [directory] [--theme <id>] [--yes]  Add Ceramic and agent instructions
   search <query>                           Search every design-system domain
   component <Name>|--list                 Inspect component contracts
+  registry <block-id>|--list              Inspect agent-editable block definitions
+  layout validate <file>                  Validate versioned Ceramic Layout JSON
+  layout serialize <file>                 Print canonical Ceramic Layout JSON
+  block <id>|--list [--copy <directory>]  Inspect or copy a composed interaction block
   template <id>|--list [--skeleton]       Inspect starter structures
   template <id> --copy <directory> [--theme <id>]
                                               Generate a themed runnable project
@@ -237,10 +254,10 @@ function copyTemplateProject(entry) {
   const workspaceCli = resolve(process.cwd(), 'packages/design-system-cli')
   const designSystemDependency = existsSync(join(workspacePackage, 'package.json'))
     ? `file:${workspacePackage}`
-    : '^0.3.0'
+    : designSystemVersion
   const cliDependency = existsSync(join(workspaceCli, 'package.json'))
     ? `file:${workspaceCli}`
-    : '^0.3.0'
+    : `^${cliVersion}`
   write(join(target, 'package.json'), `${JSON.stringify({
     name: packageName,
     private: true,
@@ -253,16 +270,62 @@ function copyTemplateProject(entry) {
       'lucide-react': '^1.23.0',
       react: '^19.0.0',
       'react-dom': '^19.0.0',
+      ...(entry.packageDependencies ?? {}),
     },
     devDependencies: { '@utopia-studio-design/design-system-cli': cliDependency, '@vitejs/plugin-react': '^4.3.4', typescript: '^5.7.2', vite: '^6.0.7' },
   }, null, 2)}\n`)
   write(join(target, '.ceramic/config.json'), `${JSON.stringify({ apiVersion: 1, theme, motionProfile: getTheme(theme)?.motionProfile, motionAdapter: 'framer-motion', arabicFriendly: true, source: '@utopia-studio-design/design-system' }, null, 2)}\n`)
-  write(join(target, 'vite.config.ts'), `import { resolve } from 'node:path'\nimport react from '@vitejs/plugin-react'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [react()],\n  build: {\n    rollupOptions: {\n      input: {\n        home: resolve('index.html'),\n        product: resolve('product/index.html'),\n        agents: resolve('agents/index.html'),\n        integrations: resolve('integrations/index.html'),\n        integrationDetail: resolve('integrations/slack/index.html'),\n        customers: resolve('customers/index.html'),\n        customerStory: resolve('customers/aster-labs/index.html'),\n        pricing: resolve('pricing/index.html'),\n        changelog: resolve('changelog/index.html'),\n        contactSales: resolve('contact-sales/index.html'),\n      },\n    },\n  },\n})\n`)
+  const htmlEntries = []
+  const collectHtml = (directory, prefix = '') => {
+    for (const name of readdirSync(directory)) {
+      const path = join(directory, name)
+      const relative = prefix ? `${prefix}/${name}` : name
+      if (statSync(path).isDirectory()) collectHtml(path, relative)
+      else if (name.endsWith('.html')) htmlEntries.push(relative)
+    }
+  }
+  collectHtml(target)
+  const viteInputs = htmlEntries.map((path, index) => `        page${index + 1}: resolve('${path}'),`).join('\n')
+  write(join(target, 'vite.config.ts'), `import { resolve } from 'node:path'\nimport react from '@vitejs/plugin-react'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [react()],\n  build: {\n    rollupOptions: {\n      input: {\n${viteInputs}\n      },\n      output: {\n        manualChunks(id) {\n          if (id.includes('node_modules/@dnd-kit/')) return 'puck-dnd'\n          if (id.includes('node_modules/@tanstack/react-virtual')) return 'puck-virtual'\n          if (id.includes('node_modules/@radix-ui/')) return 'radix'\n          if (\n            id.includes('node_modules/clsx')\n            || id.includes('node_modules/class-variance-authority')\n            || id.includes('node_modules/tailwind-merge')\n            || id.includes('node_modules/tiny-invariant')\n          ) return 'ui-utils'\n          if (id.includes('node_modules/react-dom') || id.includes('node_modules/react/')) return 'react'\n          return undefined\n        },\n      },\n    },\n  },\n})\n`)
   const existingReadme = readFileSync(join(target, 'README.md'), 'utf8')
-  write(join(target, 'README.md'), `# Generated Ceramic SaaS website\n\nActive theme: \`${theme}\`\n\n\`\`\`sh\nnpm install\nnpm run dev\n\`\`\`\n\nOpen \`http://localhost:5173/?seed=1974341818\`. All ten page entries share the same seed, theme, and locale state.\n\n${existingReadme}`)
+  write(join(target, 'README.md'), `# Generated ${entry.title}\n\nActive theme: \`${theme}\`\n\n\`\`\`sh\nnpm install\nnpm run dev\n\`\`\`\n\nOpen \`http://localhost:5173/\`.\n\n${existingReadme}`)
   output('template-copy-result', { ok: true, id: entry.id, target, theme, pages: entry.pages ?? [] }, (data) => `Generated ${data.id} with theme ${data.theme} in ${data.target}.\nNext: cd ${data.target} && npm install && npm run dev`)
 }
 
+function copyBlock(entry) {
+  const requestedTarget = argAfter('--copy', entry.id)
+  if (!requestedTarget) return
+  const target = resolve(requestedTarget)
+  if (existsSync(target) && !args.includes('--force')) return fail(`Target already exists: ${target}. Pass --force to overwrite it.`, 'ERR_TARGET_EXISTS')
+  const source = resolve(dirname(new URL(import.meta.url).pathname), '..', 'data', entry.bundlePath)
+  if (!existsSync(source)) return fail(`Block bundle is missing for "${entry.id}".`, 'ERR_BLOCK_BUNDLE')
+  cpSync(source, target, { recursive: true, force: args.includes('--force') })
+  output('block-copy-result', { ok: true, id: entry.id, target }, (data) => `Copied ${data.id} to ${data.target}.`)
+}
+
+function readLayoutInput() {
+  const file = values[1]
+  if (!file) {
+    fail('Layout command requires a JSON file path.', 'ERR_LAYOUT_FILE')
+    return null
+  }
+  const path = resolve(file)
+  if (!existsSync(path)) {
+    fail(`Layout file not found: ${path}.`, 'ERR_LAYOUT_FILE')
+    return null
+  }
+  try {
+    return { path, document: JSON.parse(readFileSync(path, 'utf8')) }
+  } catch (cause) {
+    fail(
+      `Layout file is not valid JSON: ${path}.`,
+      'ERR_LAYOUT_JSON',
+      [cause instanceof Error ? cause.message : 'Unknown JSON parse error'],
+    )
+    return null
+  }
+}
+
 function validateCommunityTemplate({ submit = false } = {}) {
   const target = resolve(values[1] ?? process.cwd())
   const result = validateTemplateSubmission(target)
@@ -301,6 +364,51 @@ else if (command === 'search') {
   const name = values[0]
   if (!name || args.includes('--list')) output('component-list', listComponents(), (rows) => rows.map((item) => `${item.name}|${item.status}|${item.category}|${item.packageImport}`).join(dense ? '\n' : '\n- '))
   else { const item = getComponent(name); item ? output('component', item, formatComponent) : fail(`Unknown component "${name}".`, 'ERR_COMPONENT', search(name).slice(0, 5).map((result) => result.id)) }
+} else if (command === 'registry') {
+  const name = values[0]
+  if (!name || args.includes('--list')) {
+    const definitions = listBlockDefinitions({ renderableOnly: args.includes('--renderable') })
+    output('block-definition-list', definitions, (rows) =>
+      rows.map((item) => `${item.id}|${item.availability}|${item.category}|${item.title}`).join('\n'))
+  } else {
+    const item = getBlockDefinition(name)
+    item ? output('block-definition', item) : fail(`Unknown block definition "${name}".`, 'ERR_BLOCK_DEFINITION')
+  }
+} else if (command === 'layout') {
+  const action = values[0]
+  if (!['validate', 'serialize'].includes(action)) {
+    fail('Layout requires "validate" or "serialize".', 'ERR_LAYOUT_ACTION')
+  } else {
+    const input = readLayoutInput()
+    if (input && action === 'validate') {
+      const result = validateLayout(input.document)
+      output('layout-validation-result', { ...result, path: input.path })
+      if (!result.ok) process.exitCode = 1
+    } else if (input) {
+      try {
+        const serialized = serializeLayout(input.document)
+        if (json) output('layout-serialization-result', { ok: true, path: input.path, serialized })
+        else process.stdout.write(serialized)
+      } catch (cause) {
+        fail(
+          'Ceramic layout validation failed.',
+          'ERR_LAYOUT_INVALID',
+          cause instanceof Error && Array.isArray(cause.issues)
+            ? cause.issues.map((issue) => `${issue.code}: ${issue.path} ${issue.message}`)
+            : [],
+        )
+      }
+    }
+  }
+} else if (command === 'block') {
+  const name = values[0]
+  if (!name || args.includes('--list')) output('block-list', listBlocks(), (rows) => rows.map((item) => `${item.id}|${item.category}|${item.title}|${item.purpose}`).join('\n'))
+  else {
+    const item = getBlock(name)
+    if (!item) fail(`Unknown block "${name}".`, 'ERR_BLOCK')
+    else if (args.includes('--copy')) copyBlock(item)
+    else output('block', item)
+  }
 } else if (command === 'template') {
   const name = values[0]
   if (name === 'validate') validateCommunityTemplate()
@@ -326,6 +434,6 @@ else if (command === 'search') {
   if (!topic || args.includes('--list')) output('docs-list', listDocs(), (rows) => rows.join('\n'))
   else { const item = getDoc(topic); item ? output('docs', item, (doc) => dense ? doc.content.replace(/\n{2,}/g, '\n').trim() : doc.content) : fail(`Unknown docs topic "${topic}".`, 'ERR_DOCS', listDocs()) }
 } else if (command === 'doctor') {
-  const result = repositoryDoctor(); output('doctor-result', result, (data) => data.ok ? `Ceramic doctor passed. ${data.checks.components} components, ${data.checks.templates} templates, ${data.checks.themes} themes, ${data.checks.motionProfiles} motion profiles, MCP ready.` : `Ceramic doctor failed: ${data.missing.join(', ')}`); if (!result.ok) process.exitCode = 1
+  const result = repositoryDoctor(); output('doctor-result', result, (data) => data.ok ? `Ceramic doctor passed. ${data.checks.components} components, ${data.checks.blocks} blocks, ${data.checks.templates} templates, ${data.checks.themes} themes, ${data.checks.motionProfiles} motion profiles, MCP ready.` : `Ceramic doctor failed: ${data.missing.join(', ')}`); if (!result.ok) process.exitCode = 1
 } else if (command === 'mcp') runMcp()
 else fail(`Unknown command "${command}".`, 'ERR_COMMAND', capabilityManifest().commands.map((item) => item.name))

package/data/blocks/activity-feed/ActivityFeedBlock.tsx

@@ -0,0 +1,255 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import { StatusDot } from '@utopia-studio-design/design-system/DataDisplay'
+import './activity-feed.css'
+
+export type ActivityFeedDensity = 'compact' | 'default' | 'comfortable'
+export type ActivityFeedGrouping = 'none' | 'day' | 'source'
+export type ActivityFeedState = 'loading' | 'empty' | 'error' | 'ready'
+export type ActivityFeedTone = 'neutral' | 'info' | 'positive' | 'warning' | 'critical'
+
+export interface ActivityFeedItem {
+  id: string
+  label: string
+  source?: string
+  timestamp: string
+  tone?: ActivityFeedTone
+}
+
+export interface ActivityFeedLabels {
+  end: string
+  emptyDescription: string
+  emptyTitle: string
+  errorDescription: string
+  errorTitle: string
+  eyebrow: string
+  invalidTime: string
+  loadMore: string
+  loading: string
+  otherSource: string
+  retry: string
+  title: string
+}
+
+export interface ActivityFeedBlockProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  density?: ActivityFeedDensity
+  direction?: 'ltr' | 'rtl'
+  groupBy?: ActivityFeedGrouping
+  items?: ActivityFeedItem[]
+  labels: ActivityFeedLabels
+  locale?: string
+  onRetry?: () => void
+  pageSize?: number
+  showSources?: boolean
+  state?: ActivityFeedState
+  timeZone?: string
+  title?: string
+}
+
+interface ActivityGroup {
+  id: string
+  label?: string
+  items: ActivityFeedItem[]
+}
+
+function safeDate(timestamp: string) {
+  const date = new Date(timestamp)
+  return Number.isNaN(date.valueOf()) ? null : date
+}
+
+function makeFormatter(locale: string, timeZone: string, options: Intl.DateTimeFormatOptions) {
+  try {
+    return new Intl.DateTimeFormat(locale, { ...options, timeZone })
+  } catch {
+    return new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' })
+  }
+}
+
+function formatNumber(locale: string, value: number) {
+  try {
+    return new Intl.NumberFormat(locale).format(value)
+  } catch {
+    return String(value)
+  }
+}
+
+function groupItems(
+  items: ActivityFeedItem[],
+  groupBy: ActivityFeedGrouping,
+  locale: string,
+  timeZone: string,
+  otherSource: string,
+): ActivityGroup[] {
+  if (groupBy === 'none') return [{ id: 'all', items }]
+
+  const dayFormatter = makeFormatter(locale, timeZone, {
+    dateStyle: 'full',
+  })
+  const groups = new Map<string, ActivityGroup>()
+  items.forEach((item) => {
+    const date = safeDate(item.timestamp)
+    const label = groupBy === 'source'
+      ? item.source || otherSource
+      : date ? dayFormatter.format(date) : otherSource
+    const id = `${groupBy}:${label}`
+    const group = groups.get(id) ?? { id, label, items: [] }
+    group.items.push(item)
+    groups.set(id, group)
+  })
+  return [...groups.values()]
+}
+
+function ActivityItems({
+  items,
+  labels,
+  locale,
+  showSources,
+  timeZone,
+}: {
+  items: ActivityFeedItem[]
+  labels: ActivityFeedLabels
+  locale: string
+  showSources: boolean
+  timeZone: string
+}) {
+  const dateTimeFormatter = makeFormatter(locale, timeZone, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  })
+  const timeFormatter = makeFormatter(locale, timeZone, {
+    hour: 'numeric',
+    minute: '2-digit',
+  })
+
+  return (
+    <ol className="ceramic-activity-items">
+      {items.map((item) => {
+        const date = safeDate(item.timestamp)
+        const accessibleTime = date ? dateTimeFormatter.format(date) : labels.invalidTime
+        const visibleTime = date ? timeFormatter.format(date) : labels.invalidTime
+        return (
+          <li key={item.id}>
+            <StatusDot
+              aria-hidden="true"
+              className="ceramic-activity-marker"
+              data-tone={item.tone ?? 'neutral'}
+            />
+            <div className="ceramic-activity-copy">
+              <p>{item.label}</p>
+              <div>
+                <time dateTime={date ? date.toISOString() : undefined} title={accessibleTime}>
+                  {visibleTime}
+                </time>
+                {showSources && item.source ? <Badge variant="outline">{item.source}</Badge> : null}
+              </div>
+            </div>
+          </li>
+        )
+      })}
+    </ol>
+  )
+}
+
+export function ActivityFeedBlock({
+  density = 'default',
+  direction,
+  groupBy = 'day',
+  items = [],
+  labels,
+  locale = 'en-US',
+  onRetry,
+  pageSize = 4,
+  showSources = true,
+  state: stateProp,
+  timeZone = 'UTC',
+  title,
+  ...props
+}: ActivityFeedBlockProps) {
+  const titleId = React.useId()
+  const [visibleCount, setVisibleCount] = React.useState(pageSize)
+  const state = stateProp ?? (items.length ? 'ready' : 'empty')
+  const visibleItems = items.slice(0, visibleCount)
+  const groups = groupItems(visibleItems, groupBy, locale, timeZone, labels.otherSource)
+  const hasMore = visibleCount < items.length
+  const visibleCountLabel = formatNumber(locale, visibleItems.length)
+  const totalCountLabel = formatNumber(locale, items.length)
+
+  React.useEffect(() => {
+    setVisibleCount(pageSize)
+  }, [items.length, pageSize])
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-labelledby={titleId}
+      className="ceramic-activity-feed"
+      data-density={density}
+      data-state={state}
+      dir={direction}
+      lang={locale}
+      {...props}
+    >
+      <header>
+        <div>
+          <span>{labels.eyebrow}</span>
+          <h2 id={titleId}>{title ?? labels.title}</h2>
+        </div>
+        {state === 'ready' ? <Badge variant="outline">{visibleCountLabel}/{totalCountLabel}</Badge> : null}
+      </header>
+
+      {state === 'loading' ? (
+        <div className="ceramic-activity-state" role="status">{labels.loading}</div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-activity-state" role="alert">
+          <strong>{labels.errorTitle}</strong>
+          <span>{labels.errorDescription}</span>
+          {onRetry ? <Button size="sm" variant="outline" onClick={onRetry}>{labels.retry}</Button> : null}
+        </div>
+      ) : null}
+      {state === 'empty' ? (
+        <div className="ceramic-activity-state" role="status">
+          <strong>{labels.emptyTitle}</strong>
+          <span>{labels.emptyDescription}</span>
+        </div>
+      ) : null}
+      {state === 'ready' ? (
+        <div className="ceramic-activity-groups">
+          {groups.map((group, groupIndex) => {
+            const groupTitleId = `${titleId}-group-${groupIndex + 1}`
+            return (
+              <section aria-labelledby={group.label ? groupTitleId : undefined} key={group.id}>
+                {group.label ? <h3 id={groupTitleId}>{group.label}</h3> : null}
+                <ActivityItems
+                  items={group.items}
+                  labels={labels}
+                  locale={locale}
+                  showSources={showSources}
+                  timeZone={timeZone}
+                />
+              </section>
+            )
+          })}
+        </div>
+      ) : null}
+
+      {state === 'ready' ? (
+        <footer>
+          {hasMore ? (
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => setVisibleCount((count) => Math.min(items.length, count + pageSize))}
+            >
+              {labels.loadMore}
+            </Button>
+          ) : <span>{labels.end}</span>}
+        </footer>
+      ) : null}
+      <output aria-live="polite" className="uds-visually-hidden">
+        {state === 'ready' ? `${visibleCountLabel} / ${totalCountLabel}` : ''}
+      </output>
+    </section>
+  )
+}

package/data/blocks/activity-feed/README.md

@@ -0,0 +1,16 @@
+# Activity Feed block
+
+`ActivityFeedBlock` is a Ceramic composition block for chronological,
+actor-independent product activity. The product owns activity data and retry
+behavior; the Composition Registry owns density, grouping, locale, direction,
+timezone, source visibility, and page size.
+
+Use `resolveActivityFeedConfiguration` in every renderer. `direction="auto"`
+derives text direction from the locale while `direction="inherit"` follows the
+dashboard preview. Activity timestamps are formatted with the registered locale
+and IANA timezone. Raw colors, spacing, classes, and tokens are not part of the
+Layout JSON contract.
+
+The block supports `loading`, `empty`, `error`, and `ready` states. Local fixture
+pagination reveals `pageSize` items at a time; production adapters may replace
+the supplied `items` when a backend page is fetched.

package/data/blocks/activity-feed/activity-feed-contract.ts

@@ -0,0 +1,96 @@
+import { getLocaleTextDirection } from '@utopia-studio-design/design-system/Utilities'
+import type {
+  ActivityFeedBlockProps,
+  ActivityFeedLabels,
+} from './ActivityFeedBlock'
+
+export const activityFeedLocaleOptions = ['en-US', 'ar-SA', 'ar-EG', 'ar-AE'] as const
+
+export type ActivityFeedLocale = typeof activityFeedLocaleOptions[number]
+export type ActivityFeedDirection = 'inherit' | 'auto' | 'ltr' | 'rtl'
+
+export interface ActivityFeedConfiguration {
+  density: NonNullable<ActivityFeedBlockProps['density']>
+  direction?: 'ltr' | 'rtl'
+  groupBy: NonNullable<ActivityFeedBlockProps['groupBy']>
+  labels: ActivityFeedLabels
+  locale: ActivityFeedLocale
+  pageSize: number
+  showSources: boolean
+  timeZone: string
+}
+
+export interface ActivityFeedContext {
+  direction: 'ltr' | 'rtl'
+}
+
+const directionModes: ActivityFeedDirection[] = ['inherit', 'auto', 'ltr', 'rtl']
+const densities: ActivityFeedConfiguration['density'][] = ['compact', 'default', 'comfortable']
+const groupings: ActivityFeedConfiguration['groupBy'][] = ['none', 'day', 'source']
+
+const englishLabels: ActivityFeedLabels = {
+  end: 'You have reached the end of the activity.',
+  emptyDescription: 'New updates will appear here when work changes.',
+  emptyTitle: 'No activity yet',
+  errorDescription: 'Reconnect the activity source and try again.',
+  errorTitle: 'Activity unavailable',
+  eyebrow: 'Activity',
+  invalidTime: 'Time unavailable',
+  loadMore: 'Load more',
+  loading: 'Loading activity…',
+  otherSource: 'Other',
+  retry: 'Try again',
+  title: 'Recent activity',
+}
+
+const arabicLabels: ActivityFeedLabels = {
+  end: 'وصلت إلى نهاية سجل النشاط.',
+  emptyDescription: 'ستظهر التحديثات الجديدة هنا عند تغيّر العمل.',
+  emptyTitle: 'لا يوجد نشاط بعد',
+  errorDescription: 'أعد الاتصال بمصدر النشاط ثم حاول مرة أخرى.',
+  errorTitle: 'النشاط غير متاح',
+  eyebrow: 'النشاط',
+  invalidTime: 'الوقت غير متاح',
+  loadMore: 'تحميل المزيد',
+  loading: 'جارٍ تحميل النشاط…',
+  otherSource: 'أخرى',
+  retry: 'حاول مرة أخرى',
+  title: 'النشاط الأخير',
+}
+
+export function getActivityFeedLabels(locale: string): ActivityFeedLabels {
+  return getLocaleTextDirection(locale) === 'rtl' ? arabicLabels : englishLabels
+}
+
+export function resolveActivityFeedConfiguration(
+  props: Record<string, unknown>,
+  context: ActivityFeedContext,
+): ActivityFeedConfiguration {
+  const locale = activityFeedLocaleOptions.includes(props.locale as ActivityFeedLocale)
+    ? props.locale as ActivityFeedLocale
+    : 'en-US'
+  const directionMode = directionModes.includes(props.direction as ActivityFeedDirection)
+    ? props.direction as ActivityFeedDirection
+    : 'inherit'
+  const direction = directionMode === 'inherit'
+    ? context.direction
+    : directionMode === 'auto' ? getLocaleTextDirection(locale) : directionMode
+  const pageSize = Number.isInteger(props.pageSize)
+    ? Math.min(20, Math.max(2, Number(props.pageSize)))
+    : 4
+
+  return {
+    density: densities.includes(props.density as ActivityFeedConfiguration['density'])
+      ? props.density as ActivityFeedConfiguration['density']
+      : 'default',
+    direction,
+    groupBy: groupings.includes(props.groupBy as ActivityFeedConfiguration['groupBy'])
+      ? props.groupBy as ActivityFeedConfiguration['groupBy']
+      : 'day',
+    labels: getActivityFeedLabels(locale),
+    locale,
+    pageSize,
+    showSources: props.showSources !== false,
+    timeZone: typeof props.timeZone === 'string' && props.timeZone ? props.timeZone : 'UTC',
+  }
+}

package/data/blocks/activity-feed/activity-feed-fixture.ts

@@ -0,0 +1,22 @@
+import type { ActivityFeedItem } from './ActivityFeedBlock'
+
+const activityItems: Record<'en' | 'ar', ActivityFeedItem[]> = {
+  en: [
+    { id: 'activity-1', label: 'Calendar block moved after the task list', source: 'Studio', timestamp: '2026-03-09T00:20:00.000Z', tone: 'info' },
+    { id: 'activity-2', label: 'Release QA completed without blockers', source: 'Mina', timestamp: '2026-03-09T01:10:00.000Z', tone: 'positive' },
+    { id: 'activity-3', label: 'Layout JSON published to this workspace', source: 'Agent', timestamp: '2026-03-09T02:30:00.000Z', tone: 'positive' },
+    { id: 'activity-4', label: 'Design-system package data synchronized', source: 'CLI', timestamp: '2026-03-08T06:40:00.000Z', tone: 'neutral' },
+    { id: 'activity-5', label: 'Arabic calendar review requested', source: 'Studio', timestamp: '2026-03-08T08:15:00.000Z', tone: 'warning' },
+  ],
+  ar: [
+    { id: 'activity-1', label: 'نُقلت كتلة التقويم بعد قائمة المهام', source: 'الاستوديو', timestamp: '2026-03-09T00:20:00.000Z', tone: 'info' },
+    { id: 'activity-2', label: 'اكتمل فحص الإصدار من دون عوائق', source: 'مينا', timestamp: '2026-03-09T01:10:00.000Z', tone: 'positive' },
+    { id: 'activity-3', label: 'نُشر ملف تخطيط JSON في مساحة العمل', source: 'الوكيل', timestamp: '2026-03-09T02:30:00.000Z', tone: 'positive' },
+    { id: 'activity-4', label: 'تمت مزامنة بيانات حزمة نظام التصميم', source: 'CLI', timestamp: '2026-03-08T06:40:00.000Z', tone: 'neutral' },
+    { id: 'activity-5', label: 'طُلبت مراجعة التقويم العربي', source: 'الاستوديو', timestamp: '2026-03-08T08:15:00.000Z', tone: 'warning' },
+  ],
+}
+
+export function getActivityFeedFixture(locale: string) {
+  return activityItems[locale.startsWith('ar') ? 'ar' : 'en']
+}