@smartcat/sanity-plugin 1.0.0 → 1.0.1

package/src/lib/locjson/portableText.ts

@@ -0,0 +1,98 @@
+import {toHTML} from '@portabletext/to-html'
+import {htmlToBlocks} from '@sanity/block-tools'
+
+/** A Portable Text block (loosely typed — shape varies by schema). */
+export type PortableTextBlock = Record<string, unknown>
+
+/** Parses an HTML string into a DOM Document. Provided by the environment. */
+export type ParseHtml = (html: string) => Document
+
+/**
+ * Renders Portable Text to an HTML string for translation.
+ * Whole-field: the entire block array becomes one HTML document fragment.
+ */
+export function portableTextToHtml(blocks: PortableTextBlock[] | undefined | null): string {
+  if (!blocks || blocks.length === 0) return ''
+  return toHTML(blocks as never, {
+    // Fallback only. Serialization skips any field containing an unserializable
+    // block up front (see findUnserializableBlockTypes), so to-html should never
+    // meet an unknown type here. If one slips through, render it as empty rather
+    // than let @portabletext/to-html emit its default placeholder — a hidden
+    // `<div style="display:none">Unknown block type "…"</div>` whose English text
+    // would otherwise be sent to Smartcat and translated into every locale.
+    // (`onMissingComponent: false` only silences the warning; it does NOT stop the
+    // placeholder — the `unknownType` override is what suppresses it.)
+    onMissingComponent: false,
+    components: {unknownType: () => ''},
+  })
+}
+
+/**
+ * Distinct `_type`s in a Portable Text value that `@portabletext/to-html` cannot
+ * serialize: any top-level member that isn't a standard `block`, or any inline
+ * child that isn't a `span` (e.g. a custom `table` block or an inline object).
+ * Such nodes render to nothing, so a field containing them can't survive the
+ * HTML round-trip — the caller skips the whole field and warns rather than
+ * silently drop or corrupt it. Marks/annotations are intentionally not included:
+ * their text survives (only the annotation would be lost).
+ */
+export function findUnserializableBlockTypes(
+  blocks: PortableTextBlock[] | undefined | null,
+): string[] {
+  if (!Array.isArray(blocks)) return []
+  const types = new Set<string>()
+  for (const block of blocks) {
+    if (!block || typeof block !== 'object') continue
+    const type = (block as {_type?: unknown})._type
+    if (type !== 'block') {
+      if (typeof type === 'string') types.add(type)
+      continue
+    }
+    const children = (block as {children?: unknown}).children
+    if (!Array.isArray(children)) continue
+    for (const child of children) {
+      const childType = (child as {_type?: unknown} | null)?._type
+      if (typeof childType === 'string' && childType !== 'span') types.add(childType)
+    }
+  }
+  return [...types].sort()
+}
+
+/**
+ * Extracts the visible text of Portable Text — the concatenation of every span's
+ * `text` across all blocks (recursing into `children`). Used to decide whether a
+ * field carries anything translatable: structural-but-textless blocks render to
+ * non-empty HTML (`<p></p>`, `<br/>`, `<ul><li></li></ul>`), so emptiness must be
+ * judged from the source blocks, not from stripping tags/entities out of the HTML
+ * (which would mishandle `&nbsp;` and void elements).
+ */
+export function portableTextToPlainText(blocks: PortableTextBlock[] | undefined | null): string {
+  if (!Array.isArray(blocks)) return ''
+  let text = ''
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit)
+    } else if (node && typeof node === 'object') {
+      const value = node as {text?: unknown; children?: unknown}
+      if (typeof value.text === 'string') text += value.text
+      if (Array.isArray(value.children)) visit(value.children)
+    }
+  }
+  visit(blocks)
+  return text
+}
+
+/**
+ * Parses translated HTML back into Portable Text using the field's compiled
+ * block content type. `parseHtml` supplies a DOM parser:
+ *   - Studio:    (html) => new DOMParser().parseFromString(html, 'text/html')
+ *   - Functions: (html) => new JSDOM(html).window.document
+ */
+export function htmlToPortableText(
+  html: string,
+  blockContentType: unknown,
+  parseHtml: ParseHtml,
+): PortableTextBlock[] {
+  if (!html.trim()) return []
+  return htmlToBlocks(html, blockContentType as never, {parseHtml}) as unknown as PortableTextBlock[]
+}

package/src/lib/locjson/serialize.ts

@@ -0,0 +1,124 @@
+import {
+  findUnserializableBlockTypes,
+  portableTextToHtml,
+  portableTextToPlainText,
+  type PortableTextBlock,
+} from './portableText'
+import {enumerateLeaves} from './fields'
+import {getAtPath} from './paths'
+import type {LocJSON, LocUnit, TranslatableField} from './types'
+
+export interface SerializeOptions {
+  sourceLanguage: string
+  /**
+   * How internationalized-array members identify their locale: a field name
+   * (e.g. `'language'`) or `'_key'` (v4.x and lower). Resolved by the caller (see
+   * `resolveConfig`); no default is assumed here.
+   */
+  fieldLanguageKey: string
+  /**
+   * Called when a Portable Text field is skipped because it contains block types
+   * that can't be serialized (see {@link findUnserializableBlockTypes}). The
+   * whole field is left out so its content isn't dropped or corrupted on the
+   * round-trip; the caller surfaces this to the user's log.
+   */
+  onSkippedField?: (info: {fieldPath: string; title?: string; types: string[]}) => void
+}
+
+/** A minimal view of a Sanity document needed for serialization. */
+export interface SerializableDocument {
+  _id: string
+  _type: string
+  _rev?: string
+  [key: string]: unknown
+}
+
+/**
+ * Serializes a Sanity document into a LocJSON file: one unit per translatable
+ * field. Plain fields become plain units (segments split on newlines); Portable
+ * Text fields become whole-field HTML units (Smartcat segments them internally).
+ *
+ * Fields with no value are skipped, so the file only contains real source text.
+ */
+export function serializeToLocjson(
+  doc: SerializableDocument,
+  fields: TranslatableField[],
+  options: SerializeOptions,
+): LocJSON {
+  const units: LocUnit[] = []
+
+  for (const field of fields) {
+    // For field-level (internationalized-array) fields the source content is the
+    // source-language member's `value` (the field may be nested through objects).
+    const source =
+      field.localization === 'field'
+        ? memberValue(getAtPath(doc, field.path), options.sourceLanguage, options.fieldLanguageKey)
+        : getAtPath(doc, field.path)
+
+    // A scalar field yields one leaf; array/object member values yield one leaf
+    // per translatable string inside (addressed by valuePath).
+    for (const leaf of enumerateLeaves(field, source)) {
+      const value = leaf.valuePath ? getAtPath(source, leaf.valuePath) : source
+      const comments = leaf.title ? [leaf.title] : undefined
+
+      if (leaf.kind === 'plain') {
+        // Skip when there's no translatable text. Trim only for the check — the
+        // stored source keeps its original whitespace so the round-trip is exact.
+        if (typeof value !== 'string' || value.trim().length === 0) continue
+        units.push({
+          key: leaf.fullKey,
+          properties: {comments, 'x-smartcat-split': 'full', 'x-sanity': {fieldPath: leaf.fullKey}},
+          // Split into line segments but keep the trailing newline on each, so
+          // concatenating the segments (LocJSON's '' join) reconstructs the original.
+          source: value.split(/(?<=\n)/),
+          target: [],
+        })
+      } else {
+        const blocks = value as PortableTextBlock[] | undefined
+        // A field with a block to-html can't serialize (e.g. a custom `table`)
+        // is skipped whole: partial HTML would drop that block on the round-trip.
+        const unserializable = findUnserializableBlockTypes(blocks)
+        if (unserializable.length > 0) {
+          options.onSkippedField?.({fieldPath: field.path, title: field.title, types: unserializable})
+          continue
+        }
+        // `html` is non-empty for structural-but-textless blocks (e.g. `<p></p>`,
+        // `<br/>`), so also require actual visible text before emitting a unit.
+        const html = portableTextToHtml(blocks)
+        if (!html || portableTextToPlainText(blocks).trim().length === 0) continue
+        units.push({
+          key: leaf.fullKey,
+          properties: {comments, 'x-smartcat-format': 'html', 'x-smartcat-split': 'full', 'x-sanity': {fieldPath: leaf.fullKey}},
+          source: [html],
+          target: [],
+        })
+      }
+    }
+  }
+
+  return {
+    properties: {
+      version: 1,
+      'x-sanity': {
+        documentId: doc._id,
+        documentType: doc._type,
+        rev: doc._rev,
+        sourceLanguage: options.sourceLanguage,
+      },
+    },
+    units,
+  }
+}
+
+/**
+ * Reads the `value` of an internationalized-array field's member for a given
+ * language. Members are identified strictly by `languageKey` — a field name
+ * (`'language'`, v5+) or `'_key'` (v4.x and lower).
+ */
+function memberValue(field: unknown, language: string, languageKey: string): unknown {
+  if (!Array.isArray(field)) return undefined
+  const member = field.find(
+    (m) => m && typeof m === 'object' && (m as Record<string, unknown>)[languageKey] === language,
+  )
+  return (member as {value?: unknown} | undefined)?.value
+}

package/src/lib/locjson/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Minimal LocJSON type definitions.
+ *
+ * LocJSON is Smartcat's JSON localization format: a set of `units`, each with a
+ * stable `key`, a `source` (array of string segments) and a `target` that
+ * Smartcat fills in. File- and unit-level `properties` may carry arbitrary
+ * `x-*` metadata that round-trips through translation.
+ */
+
+/** How a unit's content should be treated by Smartcat. "plain" is the default and is omitted. */
+export type SmartcatFormat = 'markdown' | 'html'
+
+/** Our per-document metadata, stored at file level. */
+export interface SanityFileMeta {
+  documentId: string
+  documentType: string
+  /** `_rev` at export time, to detect source drift when translations return. */
+  rev?: string
+  sourceLanguage: string
+}
+
+/** Our per-unit metadata, stored at unit level. */
+export interface SanityUnitMeta {
+  /** Path of the Sanity field this unit represents (also used as the unit key). */
+  fieldPath: string
+}
+
+export interface LocUnitProperties {
+  comments?: string[]
+  'x-smartcat-format'?: SmartcatFormat
+  'x-smartcat-split'?: 'full'
+  'x-sanity'?: SanityUnitMeta
+}
+
+export interface LocUnit {
+  /** Unique, stable id within the file. We use the Sanity field path. */
+  key: string
+  properties?: LocUnitProperties
+  source: string[]
+  target: string[]
+}
+
+export interface LocJSONProperties {
+  version: number
+  'x-sanity'?: SanityFileMeta
+}
+
+export interface LocJSON {
+  properties: LocJSONProperties
+  units: LocUnit[]
+}
+
+/** Kind of translatable field, deciding how it is serialized. */
+export type TranslatableFieldKind = 'plain' | 'portableText'
+
+/**
+ * Where a document's translations live:
+ * - `document`: separate locale documents linked via translation.metadata
+ *   (@sanity/document-internationalization).
+ * - `field`: inline per-language array members on the same document
+ *   (sanity-plugin-internationalized-array).
+ *
+ * This is a per-type property derived from the schema; it never travels in
+ * LocJSON. On a `field` field the source value is the source-language array
+ * member's `value` rather than the field itself.
+ */
+export type LocalizationMode = 'document' | 'field'
+
+/**
+ * A translatable leaf inside an array/object member value, addressed relative to
+ * that value (see `paths.ts`). `subPath` is empty for a scalar member value.
+ */
+export interface TranslatableLeaf {
+  subPath: string
+  kind: TranslatableFieldKind
+  title?: string
+}
+
+/**
+ * How a field-mode member value is shaped:
+ * - `scalar` — the value is itself the translatable leaf (string/text/Portable Text).
+ * - `arrayOfScalar` — an array of strings; one leaf per index.
+ * - `arrayOfObject` — an array of objects; the listed `leaves` per item (by `_key`).
+ * - `object` — a single object; the listed `leaves`.
+ */
+export type ValueShape =
+  | {container: 'scalar'; kind: TranslatableFieldKind}
+  | {container: 'arrayOfScalar'; kind: TranslatableFieldKind}
+  | {container: 'arrayOfObject'; leaves: TranslatableLeaf[]}
+  | {container: 'object'; leaves: TranslatableLeaf[]}
+
+/** A translatable field selected from a document/schema. */
+export interface TranslatableField {
+  /** Path to the field (dotted; nested through plain objects). Also the base unit key. */
+  path: string
+  kind: TranslatableFieldKind
+  /** How serialize extracts the source value (direct field vs. source-language array member). */
+  localization: LocalizationMode
+  /** Optional human title, surfaced to translators as a unit comment. */
+  title?: string
+  /**
+   * Shape of the (source-language member's) value. Absent means `scalar` — the
+   * historical behavior. Present when the value nests translatable leaves.
+   */
+  value?: ValueShape
+}

package/src/lib/log.ts

@@ -0,0 +1,33 @@
+/**
+ * Live, in-memory log lines for the export/import flows, streamed to the
+ * ProjectView Log panel as each document and field is processed. Never persisted
+ * — purely a session-scoped trace for troubleshooting (e.g. on client calls).
+ */
+export type LogLevel = 'info' | 'success' | 'skip' | 'error' | 'update'
+
+export interface LogLine {
+  level: LogLevel
+  message: string
+  /** Field-level lines are indented under their document header. */
+  indent?: boolean
+  /** Optional value (source or translated text); revealed on click in the panel. */
+  value?: string
+  /** Prior value; when set, the panel shows `before` and `value` side by side. */
+  before?: string
+  /** Extra detail (e.g. a JSON parse error); shown in its own box on expand. */
+  error?: string
+}
+
+/** Sink for log lines; processing accepts one to stream progress to the UI. */
+export type LogFn = (line: LogLine) => void
+
+/** Parse a Function's JSON-encoded `functionLog` field into log lines (lenient). */
+export function parseFunctionLog(raw: string | null | undefined): LogLine[] {
+  if (!raw) return []
+  try {
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? (parsed as LogLine[]) : []
+  } catch {
+    return []
+  }
+}

package/src/lib/projectItems.ts

@@ -0,0 +1,17 @@
+/**
+ * GROQ fragments for reading a translation project's `items`.
+ *
+ * An item is either the current `smartcat.projectItem` shape (`{docId, docType}`)
+ * or a legacy weak reference (`{_ref}`) from before the migration. These
+ * fragments normalize across both so the old/new tolerance lives in one place —
+ * interpolate them into item queries rather than re-writing `coalesce(...)`.
+ */
+
+/** Normalized item id, evaluated in the item's own scope (inside `items[...]`). */
+export const ITEM_ID = 'coalesce(docId, _ref)'
+
+/** Normalized item id, evaluated from a subquery nested under an item (via `^`). */
+export const ITEM_ID_FROM_SUBQUERY = 'coalesce(^.docId, ^._ref)'
+
+/** Dereference an item's document, with an optional projection e.g. `{_id, _type}`. */
+export const itemDocDeref = (projection = ''): string => `*[_id == ${ITEM_ID_FROM_SUBQUERY}][0]${projection}`

package/src/lib/resolveConfig.test.ts

@@ -0,0 +1,62 @@
+import {describe, expect, it} from 'vitest'
+import {resolveConfig} from './resolveConfig'
+import {SETTINGS_TYPE, TRANSLATION_PROJECT_TYPE} from './constants'
+
+describe('resolveConfig', () => {
+  it('applies defaults for omitted optional fields', () => {
+    const resolved = resolveConfig({sourceLanguage: 'en'})
+    expect(resolved).toMatchObject({
+      rootTypes: [],
+      sourceLanguage: 'en',
+      languages: [],
+      documentI18nLanguageField: 'language',
+      fieldI18nLanguageField: 'language',
+    })
+  })
+
+  it('treats every non-plugin type as translatable when translatableTypes is omitted', () => {
+    const {isTranslatableType} = resolveConfig({sourceLanguage: 'en'})
+    expect(isTranslatableType('page')).toBe(true)
+    expect(isTranslatableType('anythingElse')).toBe(true)
+    expect(isTranslatableType(TRANSLATION_PROJECT_TYPE)).toBe(false)
+    expect(isTranslatableType(SETTINGS_TYPE)).toBe(false)
+  })
+
+  it('restricts translatable types to the configured list', () => {
+    const {isTranslatableType} = resolveConfig({sourceLanguage: 'en', translatableTypes: ['page']})
+    expect(isTranslatableType('page')).toBe(true)
+    expect(isTranslatableType('article')).toBe(false)
+  })
+
+  it('inherits explicitly-configured translatableTypes as rootTypes', () => {
+    const resolved = resolveConfig({sourceLanguage: 'en', translatableTypes: ['page', 'article']})
+    expect(resolved.rootTypes).toEqual(['page', 'article'])
+  })
+
+  it('leaves rootTypes empty when translatableTypes is also omitted (no crawl boundary)', () => {
+    expect(resolveConfig({sourceLanguage: 'en'}).rootTypes).toEqual([])
+  })
+
+  it('honors an explicit rootTypes override independent of translatableTypes', () => {
+    const resolved = resolveConfig({
+      sourceLanguage: 'en',
+      translatableTypes: ['page', 'article'],
+      rootTypes: ['page'],
+    })
+    expect(resolved.rootTypes).toEqual(['page'])
+  })
+
+  it('honors explicit overrides (e.g. internationalized-array v4 `_key`)', () => {
+    const resolved = resolveConfig({
+      sourceLanguage: 'en',
+      documentI18nPluginLanguageField: 'lang',
+      fieldI18nPluginLanguageField: '_key',
+    })
+    expect(resolved.documentI18nLanguageField).toBe('lang')
+    expect(resolved.fieldI18nLanguageField).toBe('_key')
+  })
+
+  it('throws when sourceLanguage is missing', () => {
+    expect(() => resolveConfig({sourceLanguage: ''})).toThrow(/sourceLanguage/)
+  })
+})

package/src/lib/resolveConfig.ts

@@ -0,0 +1,47 @@
+import {requireSourceLanguage, SETTINGS_TYPE, TRANSLATION_PROJECT_TYPE} from './constants'
+import type {SmartcatLanguage, SmartcatPluginConfig} from '../types'
+
+/** The plugin's own document types, never translatable regardless of config. */
+const PLUGIN_TYPES = new Set([TRANSLATION_PROJECT_TYPE, SETTINGS_TYPE])
+
+/**
+ * Plugin config with every optional field resolved to its default. This is the
+ * single place plugin defaults are applied — notably the internationalized-array
+ * locale key, whose default (`'language'`, plugin v5+) is the one version
+ * assumption; downstream code receives a concrete value and never re-guesses.
+ */
+export interface ResolvedSmartcatConfig {
+  /**
+   * Whether a document type shows the "Add to translation project" UI. When
+   * `translatableTypes` is omitted this is true for every type except the
+   * plugin's own `smartcat.*` types; otherwise it's list membership.
+   */
+  isTranslatableType: (type: string) => boolean
+  /** Root/standalone types where the linked-documents crawl stops. */
+  rootTypes: string[]
+  sourceLanguage: string
+  languages: SmartcatLanguage[]
+  /** document-internationalization locale field (its `languageField`). */
+  documentI18nLanguageField: string
+  /** internationalized-array member locale key (`'language'` v5+, `'_key'` v4.x). */
+  fieldI18nLanguageField: string
+}
+
+export function resolveConfig(config: SmartcatPluginConfig): ResolvedSmartcatConfig {
+  const translatableTypes = config.translatableTypes
+  const isTranslatableType = translatableTypes
+    ? (type: string) => translatableTypes.includes(type)
+    : (type: string) => !PLUGIN_TYPES.has(type)
+
+  return {
+    isTranslatableType,
+    // `rootTypes` inherits the *explicitly-configured* translatableTypes (not the
+    // resolved "everything") so an unconfigured Studio gets no crawl boundary
+    // rather than every type being a root (which would stop the crawl at once).
+    rootTypes: config.rootTypes ?? translatableTypes ?? [],
+    sourceLanguage: requireSourceLanguage(config.sourceLanguage),
+    languages: config.languages ?? [],
+    documentI18nLanguageField: config.documentI18nPluginLanguageField ?? 'language',
+    fieldI18nLanguageField: config.fieldI18nPluginLanguageField ?? 'language',
+  }
+}

package/src/lib/workflow.test.ts

@@ -0,0 +1,37 @@
+import {describe, it, expect} from 'vitest'
+import {
+  isWorkflowValid,
+  resolveWorkflowCreateParams,
+  STANDARD_AI,
+  STANDARD_AI_HUMAN,
+} from './workflow'
+
+describe('isWorkflowValid', () => {
+  it('accepts the standard presets regardless of templates', () => {
+    expect(isWorkflowValid(STANDARD_AI_HUMAN, [])).toBe(true)
+    expect(isWorkflowValid(STANDARD_AI, [])).toBe(true)
+  })
+
+  it('accepts a template only while its id is still cached', () => {
+    expect(isWorkflowValid('template:abc', ['abc', 'def'])).toBe(true)
+    expect(isWorkflowValid('template:gone', ['abc', 'def'])).toBe(false)
+  })
+
+  it('rejects empty / unknown values (no selection)', () => {
+    expect(isWorkflowValid('', ['abc'])).toBe(false)
+    expect(isWorkflowValid('whatever', ['abc'])).toBe(false)
+  })
+})
+
+describe('resolveWorkflowCreateParams', () => {
+  it('maps the standard presets to workflow stages', () => {
+    expect(resolveWorkflowCreateParams(STANDARD_AI_HUMAN)).toEqual({
+      workflowStages: ['translation', 'postediting'],
+    })
+    expect(resolveWorkflowCreateParams(STANDARD_AI)).toEqual({workflowStages: ['translation']})
+  })
+
+  it('maps a template selection to a template id', () => {
+    expect(resolveWorkflowCreateParams('template:abc')).toEqual({templateId: 'abc'})
+  })
+})

package/src/lib/workflow.ts

@@ -0,0 +1,48 @@
+/**
+ * Workflow selection for new projects. A project stores a single `workflow`
+ * string: either `template:<smartcatTemplateId>` or one of the standard presets.
+ * The browser sets it at creation; the export Function decodes it into the
+ * Smartcat `createProject` params (a template id, or explicit workflow stages).
+ *
+ * Dependency-free so it bundles into the thin export Function.
+ */
+
+export const TEMPLATE_PREFIX = 'template:'
+export const STANDARD_AI_HUMAN = 'standard:ai-human'
+export const STANDARD_AI = 'standard:ai'
+
+/** Backwards-compatible default: matches the previous hard-coded behavior. */
+export const DEFAULT_WORKFLOW = STANDARD_AI_HUMAN
+
+/** Labels for the two standard presets (rendered under the "Standard workflows" group). */
+export const STANDARD_WORKFLOW_OPTIONS: {value: string; label: string}[] = [
+  {value: STANDARD_AI_HUMAN, label: 'AI Translation + Human Review'},
+  {value: STANDARD_AI, label: 'AI Translation'},
+]
+
+export interface WorkflowCreateParams {
+  templateId?: string
+  workflowStages?: string[]
+}
+
+/**
+ * Whether a `workflow` value is currently selectable: the standard presets always
+ * are; a `template:<id>` is valid only while that id still exists in the cached
+ * template list. Empty / unknown values are invalid (no selection).
+ */
+export function isWorkflowValid(workflow: string, templateIds: string[]): boolean {
+  if (workflow === STANDARD_AI_HUMAN || workflow === STANDARD_AI) return true
+  if (workflow.startsWith(TEMPLATE_PREFIX)) {
+    return templateIds.includes(workflow.slice(TEMPLATE_PREFIX.length))
+  }
+  return false
+}
+
+/** Decodes a stored `workflow` value into Smartcat create-project params. */
+export function resolveWorkflowCreateParams(workflow?: string): WorkflowCreateParams {
+  if (workflow && workflow.startsWith(TEMPLATE_PREFIX)) {
+    return {templateId: workflow.slice(TEMPLATE_PREFIX.length)}
+  }
+  if (workflow === STANDARD_AI) return {workflowStages: ['translation']}
+  return {workflowStages: ['translation', 'postediting']}
+}

package/src/lib/zip.fixtures.ts

@@ -0,0 +1,75 @@
+/**
+ * Test-only ZIP builder: assembles a minimal, structurally valid archive
+ * (local headers + central directory + EOCD) for exercising the reader.
+ * CRCs are zeroed — the reader doesn't verify them, and neither do we.
+ */
+
+export interface ZipFixtureEntry {
+  name: string
+  content: string
+  /** 0 = stored (default), 8 = deflate. */
+  method?: 0 | 8
+}
+
+export async function buildZip(entries: ZipFixtureEntry[]): Promise<Uint8Array> {
+  const encoder = new TextEncoder()
+  const chunks: Uint8Array[] = []
+  const central: Uint8Array[] = []
+  let offset = 0
+
+  for (const entry of entries) {
+    const method = entry.method ?? 0
+    const nameBytes = encoder.encode(entry.name)
+    const raw = encoder.encode(entry.content)
+    const data = method === 8 ? await deflateRaw(raw) : raw
+
+    const local = new Uint8Array(30 + nameBytes.length)
+    const lv = new DataView(local.buffer)
+    lv.setUint32(0, 0x04034b50, true)
+    lv.setUint16(4, 20, true) // version needed
+    lv.setUint16(8, method, true)
+    lv.setUint32(18, data.length, true) // compressed size
+    lv.setUint32(22, raw.length, true) // uncompressed size
+    lv.setUint16(26, nameBytes.length, true)
+    local.set(nameBytes, 30)
+    chunks.push(local, data)
+
+    const dir = new Uint8Array(46 + nameBytes.length)
+    const dv = new DataView(dir.buffer)
+    dv.setUint32(0, 0x02014b50, true)
+    dv.setUint16(4, 20, true) // version made by
+    dv.setUint16(6, 20, true) // version needed
+    dv.setUint16(10, method, true)
+    dv.setUint32(20, data.length, true)
+    dv.setUint32(24, raw.length, true)
+    dv.setUint16(28, nameBytes.length, true)
+    dv.setUint32(42, offset, true) // local header offset
+    dir.set(nameBytes, 46)
+    central.push(dir)
+
+    offset += local.length + data.length
+  }
+
+  const centralSize = central.reduce((sum, c) => sum + c.length, 0)
+  const eocd = new Uint8Array(22)
+  const ev = new DataView(eocd.buffer)
+  ev.setUint32(0, 0x06054b50, true)
+  ev.setUint16(8, entries.length, true) // entries on this disk
+  ev.setUint16(10, entries.length, true) // entries total
+  ev.setUint32(12, centralSize, true)
+  ev.setUint32(16, offset, true) // central directory offset
+
+  const total = offset + centralSize + eocd.length
+  const out = new Uint8Array(total)
+  let pos = 0
+  for (const chunk of [...chunks, ...central, eocd]) {
+    out.set(chunk, pos)
+    pos += chunk.length
+  }
+  return out
+}
+
+async function deflateRaw(data: Uint8Array): Promise<Uint8Array> {
+  const stream = new Blob([data.slice()]).stream().pipeThrough(new CompressionStream('deflate-raw'))
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}