@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/src/progress/progress.test.ts

@@ -0,0 +1,290 @@
+import {describe, expect, it} from 'vitest'
+import {
+  buildProgress,
+  buildStageNameMap,
+  isTargetComplete,
+  itemsFromProject,
+  runProgressSync,
+  sourceIdPrefix,
+  stagesFromDocument,
+  summarizeCompletion,
+  targetPercent,
+  type DocProgress,
+} from './index'
+import type {SmartcatProject} from '../smartcat/types'
+import {SmartcatTimeoutError} from '../smartcat/client'
+
+// Stage-id → name map mirroring Smartcat's project-level workflowStages.
+const STAGE_NAMES = [
+  {id: 'st-tr', stageType: 'translation'},
+  {id: 'st-ed', stageType: 'editing'},
+]
+
+describe('stage helpers', () => {
+  it('names document stages via the project-level stage map and clamps percentages', () => {
+    const names = buildStageNameMap({id: 'p', workflowStages: STAGE_NAMES})
+    const stages = stagesFromDocument(
+      {id: 'g_1', workflowStages: [{id: 'st-tr', progress: 100}, {id: 'st-ed', progress: 42.6}]},
+      names,
+    )
+    expect(stages).toEqual([
+      {_key: 'st-tr', name: 'Translation', percent: 100},
+      {_key: 'st-ed', name: 'Editing', percent: 43},
+    ])
+  })
+
+  it('treats missing/empty stages as not complete', () => {
+    expect(isTargetComplete([])).toBe(false)
+    expect(isTargetComplete([{name: 'T', percent: 100}])).toBe(true)
+    expect(isTargetComplete([{name: 'T', percent: 100}, {name: 'E', percent: 99}])).toBe(false)
+  })
+
+  it('averages stage percentages', () => {
+    expect(targetPercent([{name: 'T', percent: 100}, {name: 'E', percent: 50}])).toBe(75)
+    expect(targetPercent([])).toBe(0)
+  })
+
+  it('extracts the source-id prefix from a document filename', () => {
+    expect(sourceIdPrefix({id: 'g_1', name: 'About Us-f18f0d41', fullPath: 'page/About Us-f18f0d41'})).toBe('f18f0d41')
+    expect(sourceIdPrefix({id: 'g_1', filename: 'Contact-3f14f092.locjson'})).toBe('3f14f092')
+    // The prefix is the final 8 chars — robust to dashes in the title or the id
+    // prefix itself (e.g. a custom id `demo-pdpA` → prefix `demo-pdp`).
+    expect(sourceIdPrefix({id: 'g_1', name: 'Product A-demo-pdp', fullPath: 'pdpPage/Product A-demo-pdp'})).toBe('demo-pdp')
+    expect(sourceIdPrefix({id: 'g_1', filename: 'Some-Dashed-Title-3f14f092.locjson'})).toBe('3f14f092')
+    // DOTTED titles (e.g. micro-copy keys): only a literal `.locjson` may be
+    // stripped — a generic strip-after-last-dot would eat `.resetChat-11AKrV8G`
+    // and return the wrong prefix, so the document never correlates.
+    expect(sourceIdPrefix({id: 'g_1', name: 'aiAssistantModal.resetChat-11AKrV8G'})).toBe('11AKrV8G')
+    expect(sourceIdPrefix({id: 'g_1', filename: 'aiAssistantModal.resetChat-11AKrV8G.locjson'})).toBe('11AKrV8G')
+    expect(sourceIdPrefix({id: 'g_1', name: 'v2.5 Landing Page-ab12cd34'})).toBe('ab12cd34')
+  })
+
+  it('correlates a draft-sourced file to the same id as its published counterpart', () => {
+    // Draft files carry a trailing `-draft` marker; it must be stripped so both
+    // resolve to the same source id (a project holds one version, never both).
+    const published = {id: 'g_1', filename: 'page/About Us-f18f0d41.locjson'}
+    const draft = {id: 'g_2', filename: 'page/About Us-f18f0d41-draft.locjson'}
+    expect(sourceIdPrefix(published)).toBe('f18f0d41')
+    expect(sourceIdPrefix(draft)).toBe('f18f0d41')
+    expect(sourceIdPrefix(draft)).toBe(sourceIdPrefix(published))
+    // Marker stripped from the name form (no extension) too.
+    expect(sourceIdPrefix({id: 'g_3', name: 'About Us-f18f0d41-draft'})).toBe('f18f0d41')
+  })
+})
+
+const scProject: SmartcatProject = {
+  id: 'p1',
+  workflowStages: STAGE_NAMES,
+  documents: [
+    {id: '817_12', name: 'About Us-f18f0d41', targetLanguage: 'fr', workflowStages: [{id: 'st-tr', progress: 100}, {id: 'st-ed', progress: 100}]},
+    {id: '817_10', name: 'About Us-f18f0d41', targetLanguage: 'de', workflowStages: [{id: 'st-tr', progress: 30}, {id: 'st-ed', progress: 0}]},
+  ],
+}
+
+const items = [{_id: 'f18f0d41-aaaa-bbbb', title: 'About Us'}]
+
+describe('buildProgress', () => {
+  it('correlates documents to items by id prefix and groups by source doc', () => {
+    const progress = buildProgress(items, scProject, undefined, '2026-06-11T00:00:00Z')
+    expect(progress).toHaveLength(1)
+    expect(progress[0]).toMatchObject({sourceDocId: 'f18f0d41-aaaa-bbbb', title: 'About Us'})
+    const [de, fr] = progress[0].targets // sorted by language
+    expect(de).toMatchObject({language: 'de', smartcatDocumentId: '817_10', complete: false})
+    expect(fr).toMatchObject({language: 'fr', smartcatDocumentId: '817_12', complete: true})
+    expect(fr.stages).toEqual([
+      {_key: 'st-tr', name: 'Translation', percent: 100},
+      {_key: 'st-ed', name: 'Editing', percent: 100},
+    ])
+  })
+
+  it('carries imported flags over from previous progress', () => {
+    const previous: DocProgress[] = [
+      {_key: 'd', sourceDocId: 'f18f0d41-aaaa-bbbb', targets: [{_key: 'k', language: 'fr', stages: [], complete: true, imported: true}]},
+    ]
+    const progress = buildProgress(items, scProject, previous, 'now')
+    expect(progress[0].targets.find((t) => t.language === 'fr')?.imported).toBe(true)
+    expect(progress[0].targets.find((t) => t.language === 'de')?.imported).toBe(false)
+  })
+
+  it('carries a previously-stored title forward when the item has none', () => {
+    // A progress sync only has the raw `doc.title` (absent for types whose title
+    // is computed via preview), so the title stored at export time must survive.
+    const titleless = [{_id: 'f18f0d41-aaaa-bbbb'}]
+    const previous: DocProgress[] = [
+      {_key: 'd', sourceDocId: 'f18f0d41-aaaa-bbbb', title: 'Computed Name', targets: []},
+    ]
+    const progress = buildProgress(titleless, scProject, previous, 'now')
+    expect(progress[0].title).toBe('Computed Name')
+  })
+
+  it('drops documents that match no item', () => {
+    const progress = buildProgress([{_id: 'zzzzzzzz-x', title: 'Other'}], scProject, undefined, 'now')
+    expect(progress).toEqual([])
+  })
+
+  it('inverts Smartcat codes back to Sanity ids using the mapping', () => {
+    const scWithPolish: SmartcatProject = {
+      id: 'p1',
+      workflowStages: STAGE_NAMES,
+      documents: [
+        {id: '817_12', name: 'About Us-f18f0d41', targetLanguage: 'pl', workflowStages: [{id: 'st-tr', progress: 100}, {id: 'st-ed', progress: 100}]},
+      ],
+    }
+    const previous: DocProgress[] = [
+      {_key: 'd', sourceDocId: 'f18f0d41-aaaa-bbbb', targets: [{_key: 'k', language: 'PL-PL', stages: [], complete: true, imported: true}]},
+    ]
+    const progress = buildProgress(items, scWithPolish, previous, 'now', [{sanityId: 'PL-PL', smartcatLanguage: 'pl'}])
+    const target = progress[0].targets[0]
+    expect(target.language).toBe('PL-PL') // not 'pl'
+    expect(target._key).toBe('f18f0d41-aaaa-bbbb__PL-PL') // keyed on the Sanity id
+    expect(target.imported).toBe(true) // imported flag matched on the Sanity id
+  })
+
+  it('resolves items from a project shape', () => {
+    expect(itemsFromProject({items: [{doc: {_id: 'a'}}, {doc: null}]})).toEqual([{_id: 'a'}])
+  })
+
+  it('resolves items by stored id, so a draft-only item still correlates', () => {
+    // Current query projects the item's stored `docId` as `_id` (no deref), so an
+    // item whose document exists only as a draft is not dropped.
+    expect(itemsFromProject({items: [{_id: 'draftOnlyId', title: 'Draft Page'}]})).toEqual([
+      {_id: 'draftOnlyId', title: 'Draft Page'},
+    ])
+    // Items with no id at all (deleted/unresolvable) are still dropped.
+    expect(itemsFromProject({items: [{doc: null}, {}]})).toEqual([])
+  })
+})
+
+describe('summarizeCompletion', () => {
+  it('flags allDone only when every target is complete AND imported', () => {
+    const progress: DocProgress[] = [
+      {
+        _key: 'd1',
+        sourceDocId: 'doc1',
+        targets: [
+          {_key: 'a', language: 'fr', stages: [{name: 'T', percent: 100}], complete: true, imported: true},
+          {_key: 'b', language: 'de', stages: [{name: 'T', percent: 100}], complete: true, imported: false},
+        ],
+      },
+    ]
+    expect(summarizeCompletion(progress)).toMatchObject({total: 2, complete: 2, imported: 1, allDone: false, anyProgress: true})
+  })
+})
+
+describe('runProgressSync', () => {
+  function makeSanity(project: unknown) {
+    const sets: Record<string, unknown>[] = []
+    const client = {
+      fetch: (async () => project) as never,
+      patch: () => ({set: (attrs: Record<string, unknown>) => { sets.push(attrs); return {commit: async () => null} }}),
+    }
+    return {client, sets}
+  }
+
+  it('refreshes progress and nudges sent → translating once work starts', async () => {
+    const {client, sets} = makeSanity({
+      _id: 'p',
+      status: 'sent',
+      smartcatProjectId: 'sc1',
+      items: [{doc: {_id: 'f18f0d41-aaaa-bbbb'}}],
+      progress: [],
+    })
+    const smartcat = {getProject: async (): Promise<SmartcatProject> => scProject}
+
+    const {summary} = await runProgressSync({sanity: client, smartcat, projectId: 'p', now: () => 'T'})
+    expect(summary.total).toBe(2)
+    expect(summary.anyProgress).toBe(true)
+    expect(sets[0].status).toBe('translating')
+    expect(sets[0].progressSyncedAt).toBe('T')
+  })
+
+  it('does not change status when there is no progress yet', async () => {
+    const zero: SmartcatProject = {
+      id: 'sc1',
+      workflowStages: STAGE_NAMES,
+      documents: [{id: '817_12', name: 'About Us-f18f0d41', targetLanguage: 'fr', workflowStages: [{id: 'st-tr', progress: 0}]}],
+    }
+    const {client, sets} = makeSanity({
+      _id: 'p',
+      status: 'sent',
+      smartcatProjectId: 'sc1',
+      items: [{doc: {_id: 'f18f0d41-aaaa-bbbb'}}],
+      progress: [],
+    })
+    const smartcat = {getProject: async (): Promise<SmartcatProject> => zero}
+    await runProgressSync({sanity: client, smartcat, projectId: 'p', now: () => 'T'})
+    expect(sets[0].status).toBeUndefined()
+  })
+
+  it('clears lastError and does not write functionLog on success', async () => {
+    const {client, sets} = makeSanity({
+      _id: 'p',
+      status: 'sent',
+      smartcatProjectId: 'sc1',
+      items: [{doc: {_id: 'f18f0d41-aaaa-bbbb'}}],
+      progress: [],
+    })
+    const smartcat = {getProject: async (): Promise<SmartcatProject> => scProject, setRequestLogger: () => {}}
+    await runProgressSync({sanity: client, smartcat, projectId: 'p', now: () => 'T'})
+    expect(sets[0].lastError).toBeNull()
+    // functionLog is shared with export/import — a successful refresh must not touch it.
+    expect(sets[0].functionLog).toBeUndefined()
+  })
+
+  it('records a Smartcat failure instead of throwing, preserving existing progress', async () => {
+    const existing: DocProgress[] = [
+      {_key: 'k', sourceDocId: 'd', title: 'T', targets: []},
+    ]
+    const {client, sets} = makeSanity({
+      _id: 'p',
+      status: 'translating',
+      smartcatProjectId: 'sc1',
+      items: [{doc: {_id: 'd'}}],
+      progress: existing,
+    })
+    const smartcat = {
+      getProject: async (): Promise<SmartcatProject> => {
+        throw new SmartcatTimeoutError('GET', '/api/integration/v1/project/sc1', 570_000)
+      },
+      setRequestLogger: () => {},
+    }
+
+    const {error} = await runProgressSync({sanity: client, smartcat, projectId: 'p', now: () => 'T'})
+
+    expect(error).toContain('9m30s')
+    expect(sets[0].lastError).toContain('9m30s')
+    expect(sets[0].progressSyncedAt).toBe('T')
+    // The failure is captured in the log the dashboard renders...
+    const log = JSON.parse(sets[0].functionLog as string) as {level: string; message: string}[]
+    expect(log.some((l) => l.level === 'error' && l.message.includes('9m30s'))).toBe(true)
+    // ...and the existing progress is left untouched (not zeroed out).
+    expect(sets[0].progress).toBeUndefined()
+  })
+
+  it('captures request-logger error lines into functionLog', async () => {
+    const {client, sets} = makeSanity({
+      _id: 'p',
+      status: 'sent',
+      smartcatProjectId: 'sc1',
+      items: [],
+      progress: [],
+    })
+    let logger: (info: {method: string; path: string; status: number; body: string}) => void = () => {}
+    const smartcat = {
+      getProject: async (): Promise<SmartcatProject> => {
+        // Simulate the client tracing a failed call before rejecting.
+        logger({method: 'GET', path: '/project/sc1', status: 0, body: 'timed out'})
+        throw new Error('boom')
+      },
+      setRequestLogger: (l: typeof logger) => {
+        logger = l
+      },
+    }
+
+    await runProgressSync({sanity: client, smartcat, projectId: 'p', now: () => 'T'})
+
+    const log = JSON.parse(sets[0].functionLog as string) as {level: string; message: string; indent?: boolean}[]
+    expect(log).toContainEqual({level: 'error', message: 'GET /project/sc1 did not complete'})
+    expect(log).toContainEqual({level: 'error', indent: true, message: 'timed out'})
+  })
+})

package/src/schema/settings.ts

@@ -0,0 +1,55 @@
+import {defineType, defineField, defineArrayMember, type SchemaTypeDefinition} from 'sanity'
+import {CogIcon} from '@sanity/icons'
+import {SETTINGS_TYPE} from '../lib/constants'
+
+/**
+ * Workspace-wide Smartcat settings, stored as a single fixed-id document.
+ *
+ * Holds the cached project-template list. The browser bumps `templatesRequestedAt`
+ * (Studio init / create-dialog open); the `smartcat-templates` Function fetches
+ * the list from Smartcat and writes `templates` + `templatesSyncedAt` back.
+ * All fields are managed automatically — never hand-edited.
+ */
+export function createSettingsType(): SchemaTypeDefinition {
+  return defineType({
+    name: SETTINGS_TYPE,
+    title: 'Smartcat settings',
+    type: 'document',
+    icon: CogIcon,
+    fields: [
+      defineField({
+        name: 'templates',
+        title: 'Project templates',
+        type: 'array',
+        readOnly: true,
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcatTemplate',
+            fields: [
+              defineField({name: 'id', type: 'string'}),
+              defineField({name: 'name', type: 'string'}),
+            ],
+            preview: {select: {title: 'name', subtitle: 'id'}},
+          }),
+        ],
+      }),
+      // Handshake fields for the on-demand template refresh: the browser bumps
+      // `templatesRequestedAt`; the smartcat-templates Function writes
+      // `templatesSyncedAt`. Distinct fields stop the Function re-triggering on
+      // its own write (filter is delta::changedAny(templatesRequestedAt)).
+      defineField({name: 'templatesRequestedAt', type: 'datetime', readOnly: true, hidden: true}),
+      defineField({name: 'templatesSyncedAt', type: 'datetime', readOnly: true, hidden: true}),
+    ],
+    preview: {
+      select: {templates: 'templates', syncedAt: 'templatesSyncedAt'},
+      prepare({templates, syncedAt}) {
+        const count = Array.isArray(templates) ? templates.length : 0
+        return {
+          title: 'Smartcat settings',
+          subtitle: syncedAt ? `${count} template${count === 1 ? '' : 's'} cached` : 'Not synced yet',
+        }
+      },
+    },
+  })
+}

package/src/schema/translatableOptions.ts

@@ -0,0 +1,25 @@
+/**
+ * Schema option this plugin adds, mirroring how `@sanity/document-internationalization`
+ * contributes `options.documentInternationalization.exclude`.
+ *
+ * Set it on a field — or once on a custom type — to force translation of a type
+ * the default allowlist (`string`/`text`/Portable Text) would otherwise skip,
+ * e.g. a custom string alias. The kind is derived from the resolved `jsonType`.
+ */
+export interface SmartcatTranslationSchemaOptions {
+  smartcatTranslation?: {
+    /**
+     * Force this field/type into translation even when its base type isn't in the
+     * default allowlist. Overrides a `documentInternationalization.exclude` on the
+     * same field. Ignored if the type has no translatable representation.
+     */
+    include?: boolean
+  }
+}
+
+declare module 'sanity' {
+  interface StringOptions extends SmartcatTranslationSchemaOptions {}
+  interface TextOptions extends SmartcatTranslationSchemaOptions {}
+  interface ArrayOptions extends SmartcatTranslationSchemaOptions {}
+  interface ObjectOptions extends SmartcatTranslationSchemaOptions {}
+}

package/src/schema/translationProject.ts

@@ -0,0 +1,268 @@
+import {defineType, defineField, defineArrayMember, type SchemaTypeDefinition} from 'sanity'
+import {TranslateIcon} from '@sanity/icons'
+import {TRANSLATION_PROJECT_TYPE} from '../lib/constants'
+import type {TranslationProjectStatus} from '../types'
+
+/**
+ * Single source of truth for status display titles, used by both the schema's
+ * status dropdown (document editor) and the dashboard's StatusBadge. Titles are
+ * kept terse so they read well in both places.
+ */
+export const STATUS_OPTIONS: {title: string; value: TranslationProjectStatus}[] = [
+  {title: 'Draft', value: 'draft'},
+  {title: 'Queued', value: 'queued'},
+  {title: 'Sent', value: 'sent'},
+  {title: 'In progress', value: 'translating'},
+  {title: 'Importing', value: 'importing'},
+  {title: 'Downloaded', value: 'downloaded'},
+  {title: 'Completed', value: 'completed'},
+  {title: 'Error', value: 'error'},
+]
+
+/**
+ * Builds the translation-project document type.
+ *
+ * `items` holds `smartcat.projectItem` objects (a `docId`/`docType` pair), not
+ * Sanity references, so any document type can be added — including ones linked
+ * transitively — without the consumer having to enumerate every referenceable
+ * type in a reference `to` list. Reads dereference `docId` manually via GROQ.
+ */
+export function createTranslationProjectType(): SchemaTypeDefinition {
+  return defineType({
+    name: TRANSLATION_PROJECT_TYPE,
+    title: 'Translation project',
+    type: 'document',
+    icon: TranslateIcon,
+    fields: [
+      defineField({
+        name: 'name',
+        title: 'Project name',
+        type: 'string',
+        validation: (rule) => rule.required(),
+      }),
+      defineField({
+        name: 'status',
+        type: 'string',
+        // Driven by the dashboard and Functions, not edited by hand.
+        readOnly: true,
+        initialValue: 'draft',
+        options: {list: STATUS_OPTIONS, layout: 'radio'},
+      }),
+      defineField({
+        name: 'sourceLanguage',
+        title: 'Source language',
+        type: 'string',
+      }),
+      // Workflow chosen at creation: `template:<id>` or a standard preset.
+      // Read by the export Function to build Smartcat's createProject params.
+      defineField({name: 'workflow', type: 'string', readOnly: true, hidden: true}),
+      defineField({
+        name: 'targetLanguages',
+        title: 'Target languages',
+        type: 'array',
+        of: [defineArrayMember({type: 'string'})],
+        options: {layout: 'tags'},
+      }),
+      // Sanity-id → Smartcat-code mapping for this project's source + target
+      // languages, stamped by the browser at export time so the thin Functions
+      // (which can't see plugin config) can map to/from Smartcat codes.
+      defineField({
+        name: 'smartcatLanguages',
+        type: 'array',
+        readOnly: true,
+        hidden: true,
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcatLanguageMapping',
+            fields: [
+              defineField({name: 'sanityId', type: 'string'}),
+              defineField({name: 'smartcatLanguage', type: 'string'}),
+            ],
+          }),
+        ],
+      }),
+      defineField({
+        name: 'items',
+        title: 'Items',
+        description: 'Content added to this project for translation.',
+        // Populated by the "Add to translation project" action, not by hand.
+        readOnly: true,
+        type: 'array',
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcat.projectItem',
+            title: 'Project item',
+            fields: [
+              defineField({name: 'docId', title: 'Document ID', type: 'string'}),
+              defineField({name: 'docType', title: 'Document type', type: 'string'}),
+              // Set when the item was added from the published perspective, so the
+              // export translates the published document. Absent/false (incl. all
+              // legacy items) prefers the draft — see itemDocDerefRespectingDraft.
+              defineField({name: 'sourceIsPublished', title: 'Source is published', type: 'boolean'}),
+            ],
+            preview: {select: {title: 'docId', subtitle: 'docType'}},
+          }),
+        ],
+      }),
+      defineField({
+        name: 'smartcatProjectId',
+        title: 'Smartcat project ID',
+        type: 'string',
+        readOnly: true,
+        description: 'GUID of the corresponding project in Smartcat.',
+      }),
+      defineField({
+        name: 'smartcatProjectUrl',
+        title: 'Smartcat project URL',
+        type: 'url',
+        readOnly: true,
+        description: 'Link to the project in Smartcat (set by the export Function).',
+      }),
+      defineField({name: 'lastExportAt', type: 'datetime', readOnly: true}),
+      defineField({name: 'lastImportAt', type: 'datetime', readOnly: true}),
+      // Per-document, per-language, per-stage translation progress, mirrored from
+      // Smartcat. The export captures the target document ids; the progress/import
+      // Functions refresh the stage percentages; the browser sets `imported`.
+      defineField({
+        name: 'progress',
+        title: 'Translation progress',
+        type: 'array',
+        readOnly: true,
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcatDocProgress',
+            fields: [
+              defineField({name: 'sourceDocId', type: 'string'}),
+              defineField({name: 'title', type: 'string'}),
+              defineField({
+                name: 'targets',
+                type: 'array',
+                of: [
+                  defineArrayMember({
+                    type: 'object',
+                    name: 'smartcatTargetProgress',
+                    fields: [
+                      defineField({name: 'language', type: 'string'}),
+                      defineField({name: 'smartcatDocumentId', type: 'string'}),
+                      defineField({
+                        name: 'stages',
+                        type: 'array',
+                        of: [
+                          defineArrayMember({
+                            type: 'object',
+                            name: 'smartcatStageProgress',
+                            fields: [
+                              defineField({name: 'name', type: 'string'}),
+                              defineField({name: 'percent', type: 'number'}),
+                            ],
+                          }),
+                        ],
+                      }),
+                      // All stages at 100% (set by the progress/import Functions).
+                      defineField({name: 'complete', type: 'boolean'}),
+                      // A locale variant has been built from this target (set by the browser).
+                      defineField({name: 'imported', type: 'boolean'}),
+                      defineField({name: 'syncedAt', type: 'datetime'}),
+                    ],
+                  }),
+                ],
+              }),
+            ],
+          }),
+        ],
+      }),
+      // Handshake fields for the on-demand progress refresh: the browser bumps
+      // `progressRequestedAt`; the smartcat-progress Function reacts and writes
+      // `progressSyncedAt`. Keeping them distinct stops the Function re-triggering
+      // on its own write (filter is delta::changedAny(progressRequestedAt)).
+      defineField({name: 'progressRequestedAt', type: 'datetime', readOnly: true, hidden: true}),
+      defineField({name: 'progressSyncedAt', type: 'datetime', readOnly: true, hidden: true}),
+      defineField({
+        name: 'lastError',
+        title: 'Last error',
+        type: 'string',
+        readOnly: true,
+        description: 'Most recent export/import error, if any.',
+      }),
+      // JSON-encoded LogLine[] from the most recent Function run (export upload or
+      // import download). Transient diagnostic data the browser merges into its
+      // live Log panel; overwritten each run.
+      defineField({
+        name: 'functionLog',
+        type: 'text',
+        readOnly: true,
+        hidden: true,
+      }),
+      // Transient transport buffers. The browser (plugin) serializes content into
+      // `outbox`; the thin export Function uploads it. The thin import Function
+      // downloads translated files into `inbox`; the browser turns them into
+      // locale variants. Both are cleared after processing.
+      defineField({
+        name: 'outbox',
+        type: 'array',
+        readOnly: true,
+        hidden: true,
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcatOutboxItem',
+            fields: [
+              defineField({name: 'filename', type: 'string'}),
+              defineField({name: 'locjson', type: 'text'}),
+            ],
+          }),
+        ],
+      }),
+      defineField({
+        name: 'inbox',
+        type: 'array',
+        readOnly: true,
+        hidden: true,
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcatInboxItem',
+            fields: [
+              defineField({name: 'sourceDocId', type: 'string'}),
+              defineField({name: 'targetLanguage', type: 'string'}),
+              defineField({name: 'smartcatDocumentId', type: 'string'}),
+              defineField({name: 'locjson', type: 'text'}),
+            ],
+          }),
+        ],
+      }),
+      // Transient: items the browser marked for deletion. On the next export the
+      // Function deletes the Smartcat document and removes the item + its progress.
+      defineField({
+        name: 'pendingDeletions',
+        type: 'array',
+        readOnly: true,
+        hidden: true,
+        of: [
+          defineArrayMember({
+            type: 'object',
+            name: 'smartcatPendingDeletion',
+            fields: [
+              defineField({name: 'itemKey', type: 'string'}),
+              defineField({name: 'sourceDocId', type: 'string'}),
+              defineField({name: 'smartcatDocumentId', type: 'string'}),
+            ],
+          }),
+        ],
+      }),
+    ],
+    preview: {
+      select: {name: 'name', status: 'status', items: 'items'},
+      prepare({name, status, items}) {
+        const count = Array.isArray(items) ? items.length : 0
+        return {
+          title: name || 'Untitled project',
+          subtitle: `${status || 'draft'} · ${count} item${count === 1 ? '' : 's'}`,
+        }
+      },
+    },
+  })
+}