@formfeed/devkit 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/devkit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Formfeed template folders, project config and local rendering, shared by the CLI and @formfeed/testing.",
   "license": "MIT",
   "type": "module",
@@ -30,8 +30,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@formfeed/engine": "0.1.0",
-    "@formfeed/sdk": "0.1.0"
+    "@formfeed/engine": "0.3.0",
+    "@formfeed/sdk": "0.3.0"
   },
   "keywords": [
     "formfeed",

package/types/index.d.cts

@@ -1,7 +1,16 @@
 export { DevkitError } from './lib/errors.cjs';
 export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.cjs';
 export type { Project, ProjectConfig } from './lib/project-config.cjs';
-export { contentHash, defaultData, listTemplateSlugs, partialResolver, readState, readTemplate, recordSync, templateDir, titleFromSlug, versionPayload, writeState, writeTemplate, } from './lib/project.cjs';
-export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.cjs';
-export { diagnose, previewDocument, renderContext, renderLocal } from './lib/local-render.cjs';
+export { contentHash, defaultData, listTemplateSlugs, officeVersionPayload, partialContentHash, partialResolver, readState, readTemplate, recordSharedPartial, recordSync, sharedPartialNames, sharedPartialPath, templateDir, templateFileName, titleFromSlug, versionPayload, writePartials, writeState, writeTemplate, } from './lib/project.cjs';
+export type { LocalOfficeFile, LocalTemplate, ProjectState, SharedPartialState, TemplateMeta, TemplateState } from './lib/project.cjs';
+export { brandFromJson, brandPath, readBrand, writeBrand } from './lib/brand.cjs';
+export { collectPartials } from './lib/partials.cjs';
+export type { CollectedPartials } from './lib/partials.cjs';
+export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal } from './lib/local-render.cjs';
+export type { LocalDiagnostic, OfficeLocalOptions } from './lib/local-render.cjs';
+export { contentTypeFor, listLocalFiles, localFilePath, sha256File, writeLocalFile } from './lib/files.cjs';
+export type { LocalFile, LocalFileListing } from './lib/files.cjs';
 export type { LocalRenderOptions } from './lib/local-render.cjs';
+export { parseRedactPath, redactData, redactString } from './lib/redact.cjs';
+export { defaultTypesFile, generateTypes, localTypeSource } from './lib/types/index.cjs';
+export type { SchemaOrigin, TypeScriptOptions, TypeSource, TypesLanguage } from './lib/types/index.cjs';

package/types/index.d.ts

@@ -1,7 +1,16 @@
 export { DevkitError } from './lib/errors.js';
 export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.js';
 export type { Project, ProjectConfig } from './lib/project-config.js';
-export { contentHash, defaultData, listTemplateSlugs, partialResolver, readState, readTemplate, recordSync, templateDir, titleFromSlug, versionPayload, writeState, writeTemplate, } from './lib/project.js';
-export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.js';
-export { diagnose, previewDocument, renderContext, renderLocal } from './lib/local-render.js';
+export { contentHash, defaultData, listTemplateSlugs, officeVersionPayload, partialContentHash, partialResolver, readState, readTemplate, recordSharedPartial, recordSync, sharedPartialNames, sharedPartialPath, templateDir, templateFileName, titleFromSlug, versionPayload, writePartials, writeState, writeTemplate, } from './lib/project.js';
+export type { LocalOfficeFile, LocalTemplate, ProjectState, SharedPartialState, TemplateMeta, TemplateState } from './lib/project.js';
+export { brandFromJson, brandPath, readBrand, writeBrand } from './lib/brand.js';
+export { collectPartials } from './lib/partials.js';
+export type { CollectedPartials } from './lib/partials.js';
+export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal } from './lib/local-render.js';
+export type { LocalDiagnostic, OfficeLocalOptions } from './lib/local-render.js';
+export { contentTypeFor, listLocalFiles, localFilePath, sha256File, writeLocalFile } from './lib/files.js';
+export type { LocalFile, LocalFileListing } from './lib/files.js';
 export type { LocalRenderOptions } from './lib/local-render.js';
+export { parseRedactPath, redactData, redactString } from './lib/redact.js';
+export { defaultTypesFile, generateTypes, localTypeSource } from './lib/types/index.js';
+export type { SchemaOrigin, TypeScriptOptions, TypeSource, TypesLanguage } from './lib/types/index.js';

package/types/lib/brand.d.cts

@@ -0,0 +1,14 @@
+import { type BrandContext } from '@formfeed/engine';
+import type { Project } from './project-config.cjs';
+/**
+ * The organisation's brand kit as `formfeed brand pull` stores it (spec 18 §8): the `GET /brand`
+ * response, kept whole in `.formfeed/brand.json` so page defaults and the timestamp survive. Local
+ * renders take the template's `brand` from it; without the file they get the empty kit, which is
+ * also what an organisation that has set nothing renders with.
+ */
+export declare const brandPath: (project: Project) => string;
+/** The `brand` a template sees, from a stored `GET /brand` body; unknown or malformed fields fall back to the empty kit. */
+export declare function brandFromJson(json: unknown): BrandContext;
+export declare function readBrand(project: Project): BrandContext;
+/** Stores a `GET /brand` body; returns the file path. */
+export declare function writeBrand(project: Project, brand: unknown): string;

package/types/lib/brand.d.ts

@@ -0,0 +1,14 @@
+import { type BrandContext } from '@formfeed/engine';
+import type { Project } from './project-config.js';
+/**
+ * The organisation's brand kit as `formfeed brand pull` stores it (spec 18 §8): the `GET /brand`
+ * response, kept whole in `.formfeed/brand.json` so page defaults and the timestamp survive. Local
+ * renders take the template's `brand` from it; without the file they get the empty kit, which is
+ * also what an organisation that has set nothing renders with.
+ */
+export declare const brandPath: (project: Project) => string;
+/** The `brand` a template sees, from a stored `GET /brand` body; unknown or malformed fields fall back to the empty kit. */
+export declare function brandFromJson(json: unknown): BrandContext;
+export declare function readBrand(project: Project): BrandContext;
+/** Stores a `GET /brand` body; returns the file path. */
+export declare function writeBrand(project: Project, brand: unknown): string;

package/types/lib/files.d.cts

@@ -0,0 +1,32 @@
+import type { Project } from './project-config.cjs';
+/**
+ * The project's `files/` folder: the local copy of the workspace file library (spec 04 §2.3). A
+ * file's path below the folder is its library name, so `files/brand/logo.png` is what a template
+ * reaches with `asset('brand/logo.png')`, locally in `formfeed dev` and remotely after `files push`.
+ */
+export interface LocalFile {
+    /** The library name: the path below the files folder, with `/`. */
+    name: string;
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** From the extension; null for a type the library does not take. */
+    contentType: string | null;
+}
+export interface LocalFileListing {
+    files: LocalFile[];
+    /** Paths the library would refuse: an unusable name, an unknown type, too large or empty. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/** The content type the library stores for a name, going by its extension. */
+export declare function contentTypeFor(name: string): string | null;
+export declare function sha256File(bytes: Uint8Array): string;
+/** Every file below the files folder, with the ones the library would refuse listed apart. */
+export declare function listLocalFiles(project: Project): LocalFileListing;
+/** The path of a library name inside the files folder; refuses a name that would leave it. */
+export declare function localFilePath(project: Project, name: string): string;
+/** Writes a pulled file below the files folder, creating folders for names like `brand/logo.png`. */
+export declare function writeLocalFile(project: Project, name: string, bytes: Uint8Array): string;

package/types/lib/files.d.ts

@@ -0,0 +1,32 @@
+import type { Project } from './project-config.js';
+/**
+ * The project's `files/` folder: the local copy of the workspace file library (spec 04 §2.3). A
+ * file's path below the folder is its library name, so `files/brand/logo.png` is what a template
+ * reaches with `asset('brand/logo.png')`, locally in `formfeed dev` and remotely after `files push`.
+ */
+export interface LocalFile {
+    /** The library name: the path below the files folder, with `/`. */
+    name: string;
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** From the extension; null for a type the library does not take. */
+    contentType: string | null;
+}
+export interface LocalFileListing {
+    files: LocalFile[];
+    /** Paths the library would refuse: an unusable name, an unknown type, too large or empty. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/** The content type the library stores for a name, going by its extension. */
+export declare function contentTypeFor(name: string): string | null;
+export declare function sha256File(bytes: Uint8Array): string;
+/** Every file below the files folder, with the ones the library would refuse listed apart. */
+export declare function listLocalFiles(project: Project): LocalFileListing;
+/** The path of a library name inside the files folder; refuses a name that would leave it. */
+export declare function localFilePath(project: Project, name: string): string;
+/** Writes a pulled file below the files folder, creating folders for names like `brand/logo.png`. */
+export declare function writeLocalFile(project: Project, name: string, bytes: Uint8Array): string;

package/types/lib/local-render.d.cts

@@ -1,13 +1,49 @@
-import { type AssembleVendor, type Diagnostic, type RenderContext, type RenderedDocument } from '@formfeed/engine';
+import { type AssembleVendor, type BrandContext, type Diagnostic, type OfficeImageHost, type OfficeRenderResult, type RenderContext, type RenderedDocument } from '@formfeed/engine';
 import type { Project } from './project-config.cjs';
 import { type LocalTemplate } from './project.cjs';
+/**
+ * A finding of `diagnose`. Word and PowerPoint findings name the part and paragraph instead of a line
+ * (their `range` is 1:1), because a line of the extracted text means nothing in the document.
+ */
+export type LocalDiagnostic = Diagnostic & {
+    part?: string;
+    paragraph?: number;
+};
 /** The same diagnostics the editor shows: analysis of the body against the sample data plus compile errors. */
-export declare function diagnose(tpl: LocalTemplate, sampleData: unknown): Diagnostic[];
-export declare function renderContext(project: Project, tpl: LocalTemplate): RenderContext;
+export declare function diagnose(tpl: LocalTemplate, sampleData: unknown): LocalDiagnostic[];
+export interface OfficeLocalOptions {
+    locale?: string;
+    /** Where `asset()` resolves; the workspace library's CDN base for a document that leaves the machine. */
+    assetBaseUrl?: string;
+    brand?: BrandContext;
+    /** Loads and draws pictures and codes; without one, only PNG and JPEG data URLs are placed. */
+    images?: OfficeImageHost;
+    /** For snapshots: the source of the engine's placeholder nonce, so repeated runs fill alike. */
+    random?: () => number;
+}
+/** Fills a Word or PowerPoint template with the shared engine, as the render-worker does. */
+export declare function renderOfficeLocal(project: Project, tpl: LocalTemplate, data: unknown, options?: OfficeLocalOptions): Promise<OfficeRenderResult>;
+/**
+ * The filled parts of a Word or PowerPoint document as readable text for snapshots: each part's XML,
+ * one element per line and indented, text kept beside its element, under a `--- <part> ---` line.
+ */
+export declare function officeSnapshot(filled: Uint8Array): string;
+/** Indents XML one element per line; text and the closing tag stay on the line of their element. */
+export declare function prettyXml(xml: string): string;
+/**
+ * `assetBaseUrl` is where `asset()` and relative image paths resolve: the dev server's `/files`
+ * locally, the workspace library's CDN base when the document goes to the API. Without it the
+ * references stay relative, which keeps snapshots independent of any host.
+ */
+export declare function renderContext(project: Project, tpl: LocalTemplate, assetBaseUrl?: string, brand?: BrandContext): RenderContext;
 export interface LocalRenderOptions {
     mode: 'preview' | 'print';
     locale?: string;
     vendor?: AssembleVendor;
+    /** Where `asset()` and relative image paths resolve (see `renderContext`). */
+    assetBaseUrl?: string;
+    /** The template's `brand`; `.formfeed/brand.json` (`readBrand`) when left out. */
+    brand?: BrandContext;
 }
 /** Assembles the complete document with the shared engine; no browser involved. */
 export declare function renderLocal(project: Project, tpl: LocalTemplate, data: unknown, options: LocalRenderOptions): Promise<RenderedDocument>;

package/types/lib/local-render.d.ts

@@ -1,13 +1,49 @@
-import { type AssembleVendor, type Diagnostic, type RenderContext, type RenderedDocument } from '@formfeed/engine';
+import { type AssembleVendor, type BrandContext, type Diagnostic, type OfficeImageHost, type OfficeRenderResult, type RenderContext, type RenderedDocument } from '@formfeed/engine';
 import type { Project } from './project-config.js';
 import { type LocalTemplate } from './project.js';
+/**
+ * A finding of `diagnose`. Word and PowerPoint findings name the part and paragraph instead of a line
+ * (their `range` is 1:1), because a line of the extracted text means nothing in the document.
+ */
+export type LocalDiagnostic = Diagnostic & {
+    part?: string;
+    paragraph?: number;
+};
 /** The same diagnostics the editor shows: analysis of the body against the sample data plus compile errors. */
-export declare function diagnose(tpl: LocalTemplate, sampleData: unknown): Diagnostic[];
-export declare function renderContext(project: Project, tpl: LocalTemplate): RenderContext;
+export declare function diagnose(tpl: LocalTemplate, sampleData: unknown): LocalDiagnostic[];
+export interface OfficeLocalOptions {
+    locale?: string;
+    /** Where `asset()` resolves; the workspace library's CDN base for a document that leaves the machine. */
+    assetBaseUrl?: string;
+    brand?: BrandContext;
+    /** Loads and draws pictures and codes; without one, only PNG and JPEG data URLs are placed. */
+    images?: OfficeImageHost;
+    /** For snapshots: the source of the engine's placeholder nonce, so repeated runs fill alike. */
+    random?: () => number;
+}
+/** Fills a Word or PowerPoint template with the shared engine, as the render-worker does. */
+export declare function renderOfficeLocal(project: Project, tpl: LocalTemplate, data: unknown, options?: OfficeLocalOptions): Promise<OfficeRenderResult>;
+/**
+ * The filled parts of a Word or PowerPoint document as readable text for snapshots: each part's XML,
+ * one element per line and indented, text kept beside its element, under a `--- <part> ---` line.
+ */
+export declare function officeSnapshot(filled: Uint8Array): string;
+/** Indents XML one element per line; text and the closing tag stay on the line of their element. */
+export declare function prettyXml(xml: string): string;
+/**
+ * `assetBaseUrl` is where `asset()` and relative image paths resolve: the dev server's `/files`
+ * locally, the workspace library's CDN base when the document goes to the API. Without it the
+ * references stay relative, which keeps snapshots independent of any host.
+ */
+export declare function renderContext(project: Project, tpl: LocalTemplate, assetBaseUrl?: string, brand?: BrandContext): RenderContext;
 export interface LocalRenderOptions {
     mode: 'preview' | 'print';
     locale?: string;
     vendor?: AssembleVendor;
+    /** Where `asset()` and relative image paths resolve (see `renderContext`). */
+    assetBaseUrl?: string;
+    /** The template's `brand`; `.formfeed/brand.json` (`readBrand`) when left out. */
+    brand?: BrandContext;
 }
 /** Assembles the complete document with the shared engine; no browser involved. */
 export declare function renderLocal(project: Project, tpl: LocalTemplate, data: unknown, options: LocalRenderOptions): Promise<RenderedDocument>;

package/types/lib/partials.d.cts

@@ -0,0 +1,19 @@
+import { type EngineId } from '@formfeed/engine';
+import type { Project } from './project-config.cjs';
+/**
+ * The partials a template includes, read from the project's `partials/` folder. They travel with
+ * the version (`formfeed templates push`), so a published template resolves `{% include %}` in the
+ * API and the editor, not only in the CLI.
+ *
+ * Includes nest, so every partial is analysed in turn; a name that has no file is reported instead
+ * of failing, and `validate` and `push` show it.
+ */
+export interface CollectedPartials {
+    /** name → source, the shape the API stores. */
+    partials: Record<string, string>;
+    /** Names no file in the partials folder matches. */
+    missing: string[];
+    /** Normalised names of included shared partials of the organisation (from the project state). */
+    shared: string[];
+}
+export declare function collectPartials(project: Project, engine: EngineId, sources: Array<string | undefined>): CollectedPartials;

package/types/lib/partials.d.ts

@@ -0,0 +1,19 @@
+import { type EngineId } from '@formfeed/engine';
+import type { Project } from './project-config.js';
+/**
+ * The partials a template includes, read from the project's `partials/` folder. They travel with
+ * the version (`formfeed templates push`), so a published template resolves `{% include %}` in the
+ * API and the editor, not only in the CLI.
+ *
+ * Includes nest, so every partial is analysed in turn; a name that has no file is reported instead
+ * of failing, and `validate` and `push` show it.
+ */
+export interface CollectedPartials {
+    /** name → source, the shape the API stores. */
+    partials: Record<string, string>;
+    /** Names no file in the partials folder matches. */
+    missing: string[];
+    /** Normalised names of included shared partials of the organisation (from the project state). */
+    shared: string[];
+}
+export declare function collectPartials(project: Project, engine: EngineId, sources: Array<string | undefined>): CollectedPartials;

package/types/lib/project-config.d.cts

@@ -5,8 +5,23 @@ export interface ProjectConfig {
     region?: 'eu' | 'us';
     templatesDir: string;
     partialsDir: string;
+    /** The local copy of the workspace file library (`formfeed files push|pull`). */
+    filesDir: string;
     engine: EngineId;
     ignore: string[];
+    /** Defaults of `formfeed types` (spec 19 §2.1). */
+    types?: {
+        lang?: 'ts' | 'python';
+        /** Relative to the project root; `formfeed.d.ts` or `formfeed_templates.py` when left out. */
+        out?: string;
+        /** The module the TypeScript file augments; `@formfeed/sdk`. */
+        sdkModule?: string;
+    };
+    /** Defaults of `formfeed renders pull` (spec 20 §3.3). */
+    pull?: {
+        /** Data paths redacted on every pull (`customer.*`, `items[].name`); `--redact` paths replace them, `--no-redact` skips them. */
+        redact?: string[];
+    };
 }
 export interface Project {
     root: string;
@@ -15,6 +30,7 @@ export interface Project {
     config: ProjectConfig;
     templatesDir: string;
     partialsDir: string;
+    filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */

package/types/lib/project-config.d.ts

@@ -5,8 +5,23 @@ export interface ProjectConfig {
     region?: 'eu' | 'us';
     templatesDir: string;
     partialsDir: string;
+    /** The local copy of the workspace file library (`formfeed files push|pull`). */
+    filesDir: string;
     engine: EngineId;
     ignore: string[];
+    /** Defaults of `formfeed types` (spec 19 §2.1). */
+    types?: {
+        lang?: 'ts' | 'python';
+        /** Relative to the project root; `formfeed.d.ts` or `formfeed_templates.py` when left out. */
+        out?: string;
+        /** The module the TypeScript file augments; `@formfeed/sdk`. */
+        sdkModule?: string;
+    };
+    /** Defaults of `formfeed renders pull` (spec 20 §3.3). */
+    pull?: {
+        /** Data paths redacted on every pull (`customer.*`, `items[].name`); `--redact` paths replace them, `--no-redact` skips them. */
+        redact?: string[];
+    };
 }
 export interface Project {
     root: string;
@@ -15,6 +30,7 @@ export interface Project {
     config: ProjectConfig;
     templatesDir: string;
     partialsDir: string;
+    filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */

package/types/lib/project.d.cts

@@ -1,4 +1,4 @@
-import type { EngineId, TemplateKind, TemplateSettings } from '@formfeed/engine';
+import { type EngineId, type OfficeKind, type TemplateKind, type TemplateSettings } from '@formfeed/engine';
 import type { TemplateVersion } from '@formfeed/sdk';
 import type { Project } from './project-config.cjs';
 /**
@@ -9,15 +9,29 @@ import type { Project } from './project-config.cjs';
  */
 export interface TemplateMeta {
     name: string;
-    kind: TemplateKind;
+    /** An HTML kind, or `docx`/`pptx` for Word and PowerPoint templates. */
+    kind: TemplateKind | OfficeKind;
     engine: EngineId;
     description?: string | null;
     tags?: string[];
 }
+/**
+ * The document of a Word or PowerPoint template (spec 22 §7): `template.docx` or `template.pptx`
+ * instead of `template.html`. Such a folder has no markup, style, head, header, footer or partials.
+ */
+export interface LocalOfficeFile {
+    format: OfficeKind;
+    path: string;
+    bytes: Uint8Array;
+    sha256: string;
+}
 export interface LocalTemplate {
     slug: string;
     dir: string;
     meta: TemplateMeta;
+    /** The Word or PowerPoint document; `null` for HTML templates. */
+    file: LocalOfficeFile | null;
+    /** Empty for Word and PowerPoint templates. */
     html: string;
     css: string;
     head: string;
@@ -27,6 +41,15 @@ export interface LocalTemplate {
     dataSets: Record<string, unknown>;
     dataSchema: Record<string, unknown> | null;
     i18n: Record<string, Record<string, string>> | null;
+    /** Partials the template includes, read from the project's folder; they travel with the version. */
+    partials: Record<string, string>;
+    /** Included names without a file; `validate` reports them and `push` refuses them. */
+    missingPartials: string[];
+    /**
+     * Included names that are shared partials of the organisation (recorded in the state by
+     * `formfeed partials pull|push`). They resolve live on the server, so they stay out of `partials`.
+     */
+    sharedPartials: string[];
 }
 export interface TemplateState {
     /** Checksum of the remote version the folder was pulled from or pushed as. */
@@ -35,11 +58,26 @@ export interface TemplateState {
     status: string;
     /** Hash of the local files at that moment; a different hash means local edits. */
     contentHash: string;
+    /** Word and PowerPoint templates: the document's SHA-256, so `push` uploads it only when it changed. */
+    fileSha256?: string;
+    syncedAt: string;
+}
+/** A shared partial of the organisation as last pulled or pushed (spec 18 §8). */
+export interface SharedPartialState {
+    /** The remote version; `partials push` sends it as `base_version`. */
+    version: number;
+    engine: EngineId;
+    /** Hash of the local file at that moment; a different hash means local edits. */
+    contentHash: string;
     syncedAt: string;
 }
 export interface ProjectState {
     templates: Record<string, TemplateState>;
+    /** Shared partials by name; they live in `partialsDir` as `<name>.html`. */
+    sharedPartials?: Record<string, SharedPartialState>;
 }
+/** The file a template folder is built around, by kind. */
+export declare const templateFileName: (kind: TemplateKind | string) => string;
 export declare function listTemplateSlugs(project: Project): string[];
 export declare function templateDir(project: Project, slug: string): string;
 export declare function readTemplate(project: Project, slug: string): LocalTemplate;
@@ -48,19 +86,43 @@ export declare function defaultData(tpl: LocalTemplate, name?: string): {
     name: string;
     data: unknown;
 };
+/**
+ * Writes a pulled version into the template folder. A Word or PowerPoint template needs its
+ * document as `file`; the folder then holds `template.<kind>` and none of the HTML files, so a
+ * template whose kind changed leaves nothing behind that would be read as its source.
+ */
 export declare function writeTemplate(project: Project, slug: string, meta: TemplateMeta, version: Pick<TemplateVersion, 'html' | 'css' | 'head' | 'settings' | 'sample_data' | 'data_schema' | 'i18n'> & {
     data_sets?: Record<string, unknown> | null;
-}): string;
+    partials?: Record<string, string> | null;
+}, file?: Uint8Array): string;
+/**
+ * Writes the partials of a pulled version into the project's folder (`name` or `name.html`, the
+ * two spellings `partialResolver` reads). Returns the files whose content changed, so `pull` can
+ * say that a partial shared with another template was replaced.
+ */
+export declare function writePartials(project: Project, partials: Record<string, string> | null): string[];
+/**
+ * Fields of a push request besides the document: what the API's version create takes for a Word or
+ * PowerPoint template. The document itself travels as the multipart `file`.
+ */
+export declare function officeVersionPayload(tpl: LocalTemplate): {
+    settings: Record<string, unknown>;
+    sample_data: Record<string, unknown>;
+    data_sets: Record<string, unknown>;
+    data_schema: Record<string, unknown> | null;
+    i18n: Record<string, Record<string, string>> | null;
+};
 /** Files of a push request: what the API's TemplateVersionCreate takes. */
 export declare function versionPayload(tpl: LocalTemplate): {
-    html: string;
-    css: string;
-    head: string;
+    partials?: Record<string, string> | undefined;
     settings: Record<string, unknown>;
     sample_data: Record<string, unknown>;
     data_sets: Record<string, unknown>;
     data_schema: Record<string, unknown> | null;
     i18n: Record<string, Record<string, string>> | null;
+    html: string;
+    css: string;
+    head: string;
 };
 /** Stable hash of the local files; compared with the state to detect local edits. */
 export declare function contentHash(tpl: LocalTemplate): string;
@@ -68,5 +130,19 @@ export declare function readState(project: Project): ProjectState;
 export declare function writeState(project: Project, state: ProjectState): void;
 export declare function recordSync(project: Project, slug: string, version: Pick<TemplateVersion, 'checksum' | 'number' | 'status'>, tpl: LocalTemplate): void;
 export declare function titleFromSlug(slug: string): string;
-/** Resolves `{% include %}` / partials from the project's partials folder (`name` or `name.html`). */
+/**
+ * Resolves `{% include %}` / partials from the project's partials folder (`name` or `name.html`).
+ * A name that matches a shared partial of the state only after normalisation (`Letterhead.j2` for
+ * `letterhead`) falls back to that partial's file, the way the server matches shared partials.
+ */
 export declare function partialResolver(project: Project): (name: string) => string | undefined;
+/** Where a shared partial lives locally: `<partialsDir>/<name>.html`. */
+export declare function sharedPartialPath(project: Project, name: string): string;
+/** Normalised names of the shared partials recorded for one engine; other engines' partials never resolve. */
+export declare function sharedPartialNames(project: Project, engine: EngineId): Set<string>;
+export declare const partialContentHash: (source: string) => string;
+/** Records a pulled or pushed shared partial with the remote version and the hash of `source`. */
+export declare function recordSharedPartial(project: Project, name: string, remote: {
+    version: number;
+    engine: EngineId;
+}, source: string): void;