@smartcat/sanity-plugin 1.0.0 → 1.0.1

package/src/lib/locjson/locjson.test.ts

@@ -0,0 +1,545 @@
+import {describe, expect, it, vi} from 'vitest'
+import {Schema} from '@sanity/schema'
+import {JSDOM} from 'jsdom'
+import {
+  getTranslatableFields,
+  inferTranslatableFields,
+  innerValueType,
+  localizationMode,
+  orderFieldsBy,
+} from './fields'
+import {findUnserializableBlockTypes, portableTextToHtml} from './portableText'
+import {serializeToLocjson} from './serialize'
+import {deserializeFromLocjson} from './deserialize'
+import {buildLocjsonFilename} from './filename'
+import type {LocJSON} from './types'
+
+// A schema resembling the studio's page/blogPost, with non-translatable fields
+// mixed in to exercise selection. (Object-based built-ins like slug/image/
+// reference aren't registered in a bare @sanity/schema compile, so non-text
+// fields are represented here with primitives, a plain array, and an object —
+// all of which must be excluded just the same.)
+const schema = Schema.compile({
+  name: 'test',
+  types: [
+    {
+      name: 'page',
+      type: 'document',
+      fields: [
+        {name: 'language', type: 'string', options: {documentInternationalization: {exclude: true}}},
+        {name: 'title', type: 'string'},
+        {name: 'excerpt', type: 'text'},
+        {name: 'views', type: 'number'},
+        {name: 'featured', type: 'boolean'},
+        {name: 'tags', type: 'array', of: [{type: 'string'}]},
+        {name: 'seo', type: 'object', fields: [{name: 'metaTitle', type: 'string'}]},
+        {name: 'body', type: 'array', of: [{type: 'block'}]},
+      ],
+    },
+  ],
+})
+
+const pageType = schema.get('page')
+const bodyType = pageType.fields.find((f: {name: string}) => f.name === 'body').type
+
+const parseHtml = (html: string) => new JSDOM(html).window.document
+const getBlockContentType = () => bodyType
+
+function makeBlock(text: string, marks: string[] = []) {
+  return {
+    _type: 'block',
+    _key: 'b1',
+    style: 'normal',
+    markDefs: [],
+    children: [{_type: 'span', _key: 's1', text, marks}],
+  }
+}
+
+describe('getTranslatableFields', () => {
+  it('selects string/text/portable-text and excludes the rest', () => {
+    const fields = getTranslatableFields(pageType)
+    const byPath = Object.fromEntries(fields.map((f) => [f.path, f.kind]))
+
+    expect(byPath).toEqual({title: 'plain', excerpt: 'plain', body: 'portableText'})
+    // excluded: the language field (marked via document-internationalization's
+    // field option), primitives, plain array, object
+    expect(byPath.language).toBeUndefined()
+    expect(byPath.views).toBeUndefined()
+    expect(byPath.featured).toBeUndefined()
+    expect(byPath.tags).toBeUndefined()
+    expect(byPath.seo).toBeUndefined()
+  })
+
+  it('excludes fields marked non-translatable by document-internationalization', () => {
+    const s = Schema.compile({
+      name: 'opt',
+      types: [
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [
+            {name: 'title', type: 'string'},
+            {name: 'sku', type: 'string', options: {documentInternationalization: {exclude: true}}},
+          ],
+        },
+      ],
+    })
+    const fields = getTranslatableFields(s.get('thing'))
+    expect(fields.map((f) => f.path)).toEqual(['title']) // sku skipped via the i18n option
+  })
+
+  it('never selects fields on Sanity system types (e.g. sanity.imageAsset)', () => {
+    // Built-in asset docs are referenced by image/file fields and carry plain
+    // string fields (originalFilename, path, url) that must never be translated.
+    const imageAsset = {
+      jsonType: 'object',
+      name: 'sanity.imageAsset',
+      fields: [
+        {name: 'originalFilename', type: {jsonType: 'string', name: 'string'}},
+        {name: 'path', type: {jsonType: 'string', name: 'string'}},
+        {name: 'title', type: {jsonType: 'string', name: 'string'}},
+      ],
+    }
+    expect(getTranslatableFields(imageAsset)).toEqual([])
+  })
+
+  it('honors a custom exclude list (e.g. the configured language field)', () => {
+    const fields = getTranslatableFields(pageType, {exclude: ['title']})
+    expect(fields.map((f) => f.path)).toEqual(['excerpt', 'body'])
+  })
+
+  it('opts custom-named types into translation via smartcatTranslation.include', () => {
+    const s = Schema.compile({
+      name: 'inc',
+      types: [
+        {name: 'headingString', type: 'string', options: {smartcatTranslation: {include: true}}},
+        {name: 'richText', type: 'array', of: [{type: 'block'}], options: {smartcatTranslation: {include: true}}},
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [
+            {name: 'heading', type: 'headingString'}, // custom string alias → plain
+            {name: 'tagline', type: 'string', options: {smartcatTranslation: {include: true}}}, // per-field
+            {name: 'content', type: 'richText'}, // custom PT alias → portableText
+            {name: 'plain', type: 'string'}, // still works via the default allowlist
+          ],
+        },
+      ],
+    })
+    const fields = getTranslatableFields(s.get('thing'))
+    expect(Object.fromEntries(fields.map((f) => [f.path, f.kind]))).toEqual({
+      heading: 'plain',
+      tagline: 'plain',
+      content: 'portableText',
+      plain: 'plain',
+    })
+  })
+
+  it('lets include override a document-internationalization exclude', () => {
+    const s = Schema.compile({
+      name: 'override',
+      types: [
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [
+            {
+              name: 'note',
+              type: 'string',
+              options: {documentInternationalization: {exclude: true}, smartcatTranslation: {include: true}},
+            },
+          ],
+        },
+      ],
+    })
+    expect(getTranslatableFields(s.get('thing')).map((f) => f.path)).toEqual(['note'])
+  })
+
+  it('warns and skips when an included field has no translatable representation', () => {
+    const s = Schema.compile({
+      name: 'badinc',
+      types: [
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [{name: 'count', type: 'number', options: {smartcatTranslation: {include: true}}}],
+        },
+      ],
+    })
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const fields = getTranslatableFields(s.get('thing'))
+    expect(fields).toEqual([])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('count'))
+    warn.mockRestore()
+  })
+})
+
+describe('portableTextToHtml', () => {
+  it('renders unknown/custom block types as nothing, not a placeholder', () => {
+    // A custom `table` block (no to-html component). The default behavior emits a
+    // hidden `<div style="display:none">Unknown block type "table"…</div>`, whose
+    // English text would be translated into every locale and which Smartcat
+    // rejects as unparseable HTML. It must be dropped entirely instead.
+    const blocks = [
+      makeBlock('Delivery info'),
+      {_type: 'table', _key: 't1', rows: [{_key: 'r1', _type: 'tableRow', cells: ['Region', 'Price']}]},
+    ]
+    const html = portableTextToHtml(blocks)
+    expect(html).not.toContain('Unknown block type')
+    expect(html).not.toContain('display:none')
+    expect(html).toContain('Delivery info')
+  })
+})
+
+describe('findUnserializableBlockTypes', () => {
+  const table = {_type: 'table', _key: 't1', rows: [{_key: 'r1', _type: 'tableRow', cells: ['A', 'B']}]}
+
+  it('flags custom top-level block types', () => {
+    expect(findUnserializableBlockTypes([makeBlock('text'), table])).toEqual(['table'])
+  })
+
+  it('flags custom inline children (non-span)', () => {
+    const withInline = {
+      _type: 'block',
+      _key: 'b1',
+      children: [
+        {_type: 'span', _key: 's1', text: 'see '},
+        {_type: 'stockTicker', _key: 'i1', symbol: 'HUEL'},
+      ],
+    }
+    expect(findUnserializableBlockTypes([withInline])).toEqual(['stockTicker'])
+  })
+
+  it('returns empty for standard blocks/spans', () => {
+    expect(findUnserializableBlockTypes([makeBlock('a'), makeBlock('b')])).toEqual([])
+  })
+})
+
+describe('inferTranslatableFields', () => {
+  it('never selects fields on Sanity system types (e.g. sanity.imageAsset)', () => {
+    const asset = {
+      _type: 'sanity.imageAsset',
+      originalFilename: '01-Front Shot - es-ES.jpg',
+      path: 'images/xyz/production/abc-1468x1468.jpg',
+      url: 'https://cdn.sanity.io/images/xyz/production/abc-1468x1468.jpg',
+    }
+    expect(inferTranslatableFields(asset)).toEqual([])
+  })
+})
+
+describe('orderFieldsBy', () => {
+  it('reorders data-inferred fields to match schema order (title before body)', () => {
+    // Simulate Content Lake returning keys alphabetically (body before title).
+    const inferred = inferTranslatableFields({body: [makeBlock('x')], title: 'T'})
+    expect(inferred.map((f) => f.path)).toEqual(['body', 'title'])
+
+    const ordered = orderFieldsBy(inferred, ['title', 'body'])
+    expect(ordered.map((f) => f.path)).toEqual(['title', 'body'])
+  })
+
+  it('puts unlisted fields last, preserving their order', () => {
+    const fields = inferTranslatableFields({title: 'T', body: [makeBlock('x')], summary: 'S'})
+    const ordered = orderFieldsBy(fields, ['title'])
+    expect(ordered[0].path).toBe('title')
+    expect(ordered.slice(1).map((f) => f.path).sort()).toEqual(['body', 'summary'])
+  })
+
+  it('returns fields unchanged when no order is given', () => {
+    const fields = inferTranslatableFields({title: 'T'})
+    expect(orderFieldsBy(fields, undefined)).toBe(fields)
+  })
+})
+
+describe('serializeToLocjson', () => {
+  const doc = {
+    _id: '3f14f092-3475-42fc-a9f4-abf710d71ea8',
+    _type: 'page',
+    _rev: 'rev-1',
+    language: 'en',
+    title: 'About Us',
+    excerpt: 'Line one\nLine two',
+    body: [makeBlock('We build delightful things.')],
+  }
+  const fields = getTranslatableFields(pageType)
+  const locjson = serializeToLocjson(doc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+
+  it('writes file-level x-sanity metadata', () => {
+    expect(locjson.properties['x-sanity']).toEqual({
+      documentId: doc._id,
+      documentType: 'page',
+      rev: 'rev-1',
+      sourceLanguage: 'en',
+    })
+  })
+
+  it('emits one unit per non-empty translatable field, keyed by field path', () => {
+    expect(locjson.units.map((u) => u.key)).toEqual(['title', 'excerpt', 'body'])
+  })
+
+  it('splits plain text into line segments (keeping newlines) and marks html units', () => {
+    const excerpt = locjson.units.find((u) => u.key === 'excerpt')!
+    expect(excerpt.source).toEqual(['Line one\n', 'Line two'])
+    expect(excerpt.source.join('')).toBe('Line one\nLine two')
+    expect(excerpt.properties?.['x-smartcat-format']).toBeUndefined()
+
+    const body = locjson.units.find((u) => u.key === 'body')!
+    expect(body.properties?.['x-smartcat-format']).toBe('html')
+    expect(body.source[0]).toContain('We build delightful things.')
+    expect(body.properties?.['x-sanity']).toEqual({fieldPath: 'body'})
+  })
+
+  it('skips a Portable Text field containing an unserializable block, and reports it', () => {
+    const skipped: {fieldPath: string; types: string[]}[] = []
+    const result = serializeToLocjson(
+      {
+        _id: 'x',
+        _type: 'page',
+        title: 'Delivery',
+        body: [makeBlock('How much is delivery?'), {_type: 'table', _key: 't1', rows: []}],
+      },
+      fields,
+      {
+        sourceLanguage: 'en',
+        fieldLanguageKey: 'language',
+        onSkippedField: ({fieldPath, types}) => skipped.push({fieldPath, types}),
+      },
+    )
+    // title still serialized; body left out entirely (not partially)
+    expect(result.units.map((u) => u.key)).toEqual(['title'])
+    expect(skipped).toEqual([{fieldPath: 'body', types: ['table']}])
+  })
+
+  it('skips empty fields', () => {
+    const empty = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    expect(empty.units).toHaveLength(0)
+  })
+
+  it('skips whitespace-only plain fields', () => {
+    const blank = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '   ', excerpt: '\n\n', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    expect(blank.units).toHaveLength(0)
+  })
+
+  it('skips Portable Text that renders to markup but carries no visible text', () => {
+    // An "emptied" rich-text field: the paragraph/list structure survives but the
+    // spans hold no text, so toHTML yields <p></p> / <br/> — non-empty markup that
+    // must NOT become a unit.
+    for (const body of [
+      [makeBlock('')], // <p></p>
+      [makeBlock('   ')], // <p>&nbsp; </p>
+      [makeBlock('\n')], // <p><br/></p>
+      [{_type: 'block', _key: 'b1', style: 'normal', markDefs: [], children: []}], // <p></p>
+    ]) {
+      const result = serializeToLocjson(
+        {_id: 'x', _type: 'page', title: '', body},
+        fields,
+        {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+      )
+      expect(result.units).toHaveLength(0)
+    }
+  })
+
+  it('keeps a field whose text is surrounded by whitespace (preserving it in source)', () => {
+    const result = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '  Hello  ', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    expect(result.units.map((u) => u.key)).toEqual(['title'])
+    expect(result.units[0].source.join('')).toBe('  Hello  ')
+  })
+})
+
+describe('round-trip', () => {
+  const doc = {
+    _id: 'abc12345-0000',
+    _type: 'page',
+    _rev: 'rev-1',
+    language: 'en',
+    title: 'About Us',
+    excerpt: 'Line one\nLine two',
+    body: [makeBlock('We build delightful things.', ['strong'])],
+  }
+  const fields = getTranslatableFields(pageType)
+
+  it('deserialize(serialize(doc)) preserves translatable field values', () => {
+    const locjson = serializeToLocjson(doc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    // Simulate "no-op translation": copy source into target.
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) => ({...u, target: [...u.source]})),
+    }
+
+    const result = deserializeFromLocjson(translated, {parseHtml, getBlockContentType})
+
+    expect(result.documentId).toBe(doc._id)
+    expect(result.documentType).toBe('page')
+    expect(result.fields.title).toBe('About Us')
+    expect(result.fields.excerpt).toBe('Line one\nLine two')
+
+    const body = result.fields.body as Array<Record<string, unknown>>
+    expect(Array.isArray(body)).toBe(true)
+    const spans = (body[0].children as Array<{text: string; marks: string[]}>)
+    expect(spans[0].text).toBe('We build delightful things.')
+    expect(spans[0].marks).toContain('strong')
+  })
+
+  it('uses target text when present (actual translation)', () => {
+    const locjson = serializeToLocjson(doc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) =>
+        u.key === 'title' ? {...u, target: ['À propos']} : {...u, target: [...u.source]},
+      ),
+    }
+    const result = deserializeFromLocjson(translated, {parseHtml, getBlockContentType})
+    expect(result.fields.title).toBe('À propos')
+  })
+})
+
+// --- Field-level localization (sanity-plugin-internationalized-array) ---------
+
+const faqSchema = Schema.compile({
+  name: 'faqTest',
+  types: [
+    {name: 'internationalizedArrayStringValue', type: 'object', fields: [{name: 'value', type: 'string'}]},
+    {name: 'internationalizedArrayString', type: 'array', of: [{type: 'internationalizedArrayStringValue'}]},
+    {
+      name: 'internationalizedArraySimpleBlockContentValue',
+      type: 'object',
+      fields: [{name: 'value', type: 'array', of: [{type: 'block'}]}],
+    },
+    {
+      name: 'internationalizedArraySimpleBlockContent',
+      type: 'array',
+      of: [{type: 'internationalizedArraySimpleBlockContentValue'}],
+    },
+    {
+      name: 'faq',
+      type: 'document',
+      fields: [
+        {name: 'question', type: 'internationalizedArrayString'},
+        {name: 'answer', type: 'internationalizedArraySimpleBlockContent'},
+        {name: 'note', type: 'string'}, // plain top-level field — skipped in field mode
+      ],
+    },
+  ],
+})
+const faqType = faqSchema.get('faq')
+const answerBlockType = innerValueType(faqType.fields.find((f: {name: string}) => f.name === 'answer').type)
+
+const member = (language: string, value: unknown, type = 'internationalizedArrayStringValue') => ({
+  _key: `${language}-key`,
+  _type: type,
+  language,
+  value,
+})
+
+describe('field-level localization', () => {
+  it('localizationMode is field for an internationalized-array type, document otherwise', () => {
+    expect(localizationMode(faqType)).toBe('field')
+    expect(localizationMode(pageType)).toBe('document')
+  })
+
+  it('selects only the i18n-array fields and skips plain top-level fields (homogeneity rule)', () => {
+    const fields = getTranslatableFields(faqType)
+    expect(fields.map((f) => [f.path, f.kind, f.localization])).toEqual([
+      ['question', 'plain', 'field'],
+      ['answer', 'portableText', 'field'],
+    ])
+    expect(fields.find((f) => f.path === 'note')).toBeUndefined()
+  })
+
+  it('serializes the source-language member value of each field', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [member('en', 'How?'), member('fr', 'Comment ?')],
+      answer: [
+        member('en', [makeBlock('Like this.')], 'internationalizedArraySimpleBlockContentValue'),
+      ],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    const question = locjson.units.find((u) => u.key === 'question')!
+    expect(question.source.join('')).toBe('How?')
+    const answer = locjson.units.find((u) => u.key === 'answer')!
+    expect(answer.properties?.['x-smartcat-format']).toBe('html')
+    expect(answer.source[0]).toContain('Like this.')
+  })
+
+  it('reads the source member by _key when fieldLanguageKey is "_key" (v4)', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [
+        {_key: 'en', _type: 'internationalizedArrayStringValue', value: 'How?'},
+        {_key: 'fr', _type: 'internationalizedArrayStringValue', value: 'Comment ?'},
+      ],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {
+      sourceLanguage: 'en',
+      fieldLanguageKey: '_key',
+    })
+    expect(locjson.units.find((u) => u.key === 'question')!.source.join('')).toBe('How?')
+  })
+
+  it('does not match a _key-keyed member under the "language" key (no fallback)', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [{_key: 'en', _type: 'internationalizedArrayStringValue', value: 'How?'}],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    expect(locjson.units.find((u) => u.key === 'question')).toBeUndefined()
+  })
+
+  it('round-trips field-level values (LocJSON carries no localization marker)', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [member('en', 'How?')],
+      answer: [member('en', [makeBlock('Like this.')], 'internationalizedArraySimpleBlockContentValue')],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    expect(locjson.properties['x-sanity']).not.toHaveProperty('localization')
+
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) =>
+        u.key === 'question' ? {...u, target: ['Comment ?']} : {...u, target: [...u.source]},
+      ),
+    }
+    const result = deserializeFromLocjson(translated, {
+      parseHtml,
+      getBlockContentType: (path) => (path === 'answer' ? answerBlockType : undefined),
+    })
+    expect(result.fields.question).toBe('Comment ?')
+    const body = result.fields.answer as Array<Record<string, unknown>>
+    expect((body[0].children as Array<{text: string}>)[0].text).toBe('Like this.')
+  })
+})
+
+describe('buildLocjsonFilename', () => {
+  it('builds "<type>/<title>-<idPrefix>.locjson"', () => {
+    expect(buildLocjsonFilename('page', '3f14f092-3475-42fc-a9f4-abf710d71ea8', 'About Us')).toBe(
+      'page/About Us-3f14f092.locjson',
+    )
+  })
+
+  it('strips drafts. prefix and sanitizes the title', () => {
+    expect(buildLocjsonFilename('blogPost', 'drafts.7c7b0950-aaaa', 'Why We Love / Content')).toBe(
+      'blogPost/Why We Love Content-7c7b0950.locjson',
+    )
+  })
+
+  it('falls back when title is missing', () => {
+    expect(buildLocjsonFilename('page', 'abc12345-0000')).toBe('page/Untitled-abc12345.locjson')
+  })
+})

package/src/lib/locjson/paths.test.ts

@@ -0,0 +1,41 @@
+import {describe, expect, it} from 'vitest'
+import {getAtPath, parsePath, setAtPath} from './paths'
+
+describe('parsePath', () => {
+  it('parses fields, array-by-key, and array-by-index', () => {
+    expect(parsePath('benefits.items[b1].value')).toEqual([{field: 'benefits'}, {field: 'items'}, {key: 'b1'}, {field: 'value'}])
+    expect(parsePath('tabs[2]')).toEqual([{field: 'tabs'}, {index: 2}])
+    expect(parsePath('')).toEqual([])
+  })
+})
+
+const value = [
+  {_key: 'b1', key: 'protein', value: 'High in protein'},
+  {_key: 'b2', key: 'fibre', value: 'Rich in fibre'},
+]
+
+describe('getAtPath', () => {
+  it('reads by _key and index', () => {
+    expect(getAtPath(value, '[b1].value')).toBe('High in protein')
+    expect(getAtPath(value, '[1].key')).toBe('fibre')
+    expect(getAtPath(value, '[missing].value')).toBeUndefined()
+  })
+})
+
+describe('setAtPath', () => {
+  it('replaces a leaf immutably, preserving siblings and _keys', () => {
+    const next = setAtPath(value, '[b1].value', 'PROTEINE')
+    expect(next[0]).toEqual({_key: 'b1', key: 'protein', value: 'PROTEINE'})
+    expect(next[1]).toEqual(value[1])
+    expect(value[0].value).toBe('High in protein') // original untouched
+  })
+
+  it('empty path replaces the whole value', () => {
+    expect(setAtPath('old', '', 'new')).toBe('new')
+  })
+
+  it('is a no-op when an intermediate segment is missing', () => {
+    const next = setAtPath(value, '[nope].value', 'x')
+    expect(next).toEqual(value)
+  })
+})

package/src/lib/locjson/paths.ts

@@ -0,0 +1,73 @@
+/**
+ * Tiny path grammar for addressing translatable leaves nested inside a field's
+ * value: `.field` for object properties, `[key]` for array members by `_key`,
+ * `[n]` for array members by index. Used to expand array/object member values
+ * into per-leaf LocJSON units and to overlay translations back onto a cloned
+ * source value.
+ *
+ * e.g. `items[b1].value`, `tabs[2]`, `` (empty = the value itself).
+ */
+export type PathSeg = {field: string} | {key: string} | {index: number}
+
+export function parsePath(path: string): PathSeg[] {
+  const segs: PathSeg[] = []
+  const re = /\.?([^.[\]]+)|\[([^\]]+)\]/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(path)) !== null) {
+    if (m[1] !== undefined) segs.push({field: m[1]})
+    else if (/^\d+$/.test(m[2])) segs.push({index: Number(m[2])})
+    else segs.push({key: m[2]})
+  }
+  return segs
+}
+
+/** Append a segment to a base path string, producing a valid path. */
+export function joinPath(base: string, seg: PathSeg): string {
+  if ('field' in seg) return base ? `${base}.${seg.field}` : seg.field
+  if ('index' in seg) return `${base}[${seg.index}]`
+  return `${base}[${seg.key}]`
+}
+
+function child(container: unknown, seg: PathSeg): unknown {
+  if (container == null || typeof container !== 'object') return undefined
+  if ('field' in seg) return (container as Record<string, unknown>)[seg.field]
+  if ('index' in seg) return Array.isArray(container) ? container[seg.index] : undefined
+  return Array.isArray(container)
+    ? container.find((m) => m && typeof m === 'object' && (m as Record<string, unknown>)._key === seg.key)
+    : undefined
+}
+
+/** Read the value at a path from a root value (undefined if any segment misses). */
+export function getAtPath(root: unknown, path: string): unknown {
+  let cur = root
+  for (const seg of parsePath(path)) {
+    cur = child(cur, seg)
+    if (cur === undefined) return undefined
+  }
+  return cur
+}
+
+/**
+ * Return a deep clone of `root` with the leaf at `path` replaced by `value`.
+ * An empty path replaces the whole value. Missing intermediate segments are a
+ * no-op (the clone is returned unchanged), so a template that lacks a leaf can't
+ * be corrupted.
+ */
+export function setAtPath<T>(root: T, path: string, value: unknown): T {
+  const segs = parsePath(path)
+  if (segs.length === 0) return value as T
+  const clone = structuredClone(root)
+  let cur: unknown = clone
+  for (let i = 0; i < segs.length - 1; i++) {
+    cur = child(cur, segs[i])
+    if (cur == null || typeof cur !== 'object') return clone
+  }
+  const last = segs[segs.length - 1]
+  if ('field' in last) (cur as Record<string, unknown>)[last.field] = value
+  else if ('index' in last && Array.isArray(cur)) cur[last.index] = value
+  else if ('key' in last && Array.isArray(cur)) {
+    const idx = cur.findIndex((m) => m && typeof m === 'object' && (m as Record<string, unknown>)._key === last.key)
+    if (idx >= 0) cur[idx] = value
+  }
+  return clone
+}