@formfeed/devkit 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/devkit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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.2.0",
-    "@formfeed/sdk": "0.2.0"
+    "@formfeed/engine": "0.3.1",
+    "@formfeed/sdk": "0.3.1"
   },
   "keywords": [
     "formfeed",

package/types/index.d.cts

@@ -1,11 +1,16 @@
 export { DevkitError } from './lib/errors.cjs';
-export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.cjs';
+export { defaultProjectConfig, findProject, isIgnored, 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, writePartials, writeState, writeTemplate, } from './lib/project.cjs';
-export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.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, previewDocument, renderContext, renderLocal } from './lib/local-render.cjs';
+export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal, renderedSettings } 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,11 +1,16 @@
 export { DevkitError } from './lib/errors.js';
-export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.js';
+export { defaultProjectConfig, findProject, isIgnored, 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, writePartials, writeState, writeTemplate, } from './lib/project.js';
-export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.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, previewDocument, renderContext, renderLocal } from './lib/local-render.js';
+export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal, renderedSettings } 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/local-render.d.cts

@@ -1,22 +1,58 @@
-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 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): RenderContext;
+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>;
+/**
+ * The settings to send with a locally rendered document as a raw-HTML render. The API uses
+ * `header.html`, `footer.html` and the PDF title of such a render verbatim, so they must be the
+ * filled parts, not the template's source; the inline CSS travels with them, because Chromium loads
+ * no stylesheet in its header and footer templates.
+ */
+export declare function renderedSettings(rendered: RenderedDocument): Record<string, unknown>;
 /** Wraps a preview render for the screen the way the editor does. */
 export declare function previewDocument(tpl: LocalTemplate, rendered: RenderedDocument, mode: 'flow' | 'paged', pagedScriptUrl: string): string;

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

@@ -1,22 +1,58 @@
-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 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): RenderContext;
+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>;
+/**
+ * The settings to send with a locally rendered document as a raw-HTML render. The API uses
+ * `header.html`, `footer.html` and the PDF title of such a render verbatim, so they must be the
+ * filled parts, not the template's source; the inline CSS travels with them, because Chromium loads
+ * no stylesheet in its header and footer templates.
+ */
+export declare function renderedSettings(rendered: RenderedDocument): Record<string, unknown>;
 /** Wraps a preview render for the screen the way the editor does. */
 export declare function previewDocument(tpl: LocalTemplate, rendered: RenderedDocument, mode: 'flow' | 'paged', pagedScriptUrl: string): string;

package/types/lib/partials.d.cts

@@ -13,5 +13,7 @@ export interface CollectedPartials {
     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

@@ -13,5 +13,7 @@ export interface CollectedPartials {
     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

@@ -9,6 +9,19 @@ export interface ProjectConfig {
     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;
@@ -20,6 +33,12 @@ export interface Project {
     filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
+/**
+ * Whether a path of the project matches one of `ignore`. The path is taken relative to the project
+ * root; a folder also matches as `<folder>/` and through the files in it, so `**\/drafts/**` and
+ * `templates/wip-*` both catch `templates/wip-offer`.
+ */
+export declare function isIgnored(project: Project, path: string, folder?: boolean): boolean;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */
 export declare function findProject(cwd?: string): Project | null;
 export declare function loadProject(configPath: string): Project;

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

@@ -9,6 +9,19 @@ export interface ProjectConfig {
     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;
@@ -20,6 +33,12 @@ export interface Project {
     filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
+/**
+ * Whether a path of the project matches one of `ignore`. The path is taken relative to the project
+ * root; a folder also matches as `<folder>/` and through the files in it, so `**\/drafts/**` and
+ * `templates/wip-*` both catch `templates/wip-offer`.
+ */
+export declare function isIgnored(project: Project, path: string, folder?: boolean): boolean;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */
 export declare function findProject(cwd?: string): Project | null;
 export declare function loadProject(configPath: string): Project;

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;
@@ -31,6 +45,11 @@ export interface LocalTemplate {
     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. */
@@ -39,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;
@@ -52,27 +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;
     partials?: Record<string, string> | null;
-}): string;
+}, 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): {
     partials?: Record<string, string> | undefined;
-    html: string;
-    css: string;
-    head: string;
     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;
@@ -80,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;

package/types/lib/project.d.ts

@@ -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.js';
 /**
@@ -9,15 +9,29 @@ import type { Project } from './project-config.js';
  */
 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;
@@ -31,6 +45,11 @@ export interface LocalTemplate {
     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. */
@@ -39,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;
@@ -52,27 +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;
     partials?: Record<string, string> | null;
-}): string;
+}, 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): {
     partials?: Record<string, string> | undefined;
-    html: string;
-    css: string;
-    head: string;
     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;
@@ -80,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;

package/types/lib/redact.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Shape-keeping redaction of render data (spec 20 §3.3), for `formfeed renders pull --redact`.
+ *
+ * Strings become placeholders of the same length that keep the character classes: upper-case
+ * letters become `A`, other letters `a`, digits `0`, and everything else (spaces, `@`, `.`, `-`)
+ * stays, so `jane@mail.test` becomes `aaaa@aaaa.aaaa` and `DE00 0000` becomes `AA00 0000`. Numbers,
+ * booleans and null are kept: they are usually what made the render go wrong, and they rarely
+ * identify a person. Arrays and objects keep their keys and lengths.
+ *
+ * Paths select what is redacted, from the root of the data: dotted segments (`customer.email`),
+ * `*` for any one key or array item (`customer.*`), and `[]` for every item of an array
+ * (`items[].name`, the same as `items.*.name`). A path that ends on an object or array redacts
+ * everything below it. Without paths (or with an empty list) the whole data set is redacted.
+ */
+export declare function redactData<T>(value: T, paths?: readonly string[]): T;
+/** A placeholder of the same length with the character classes of `text` kept. */
+export declare function redactString(text: string): string;
+/** `items[].name` → `['items', '*', 'name']`; `lines[0].qty` → `['lines', '0', 'qty']`. */
+export declare function parseRedactPath(path: string): string[];

package/types/lib/redact.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shape-keeping redaction of render data (spec 20 §3.3), for `formfeed renders pull --redact`.
+ *
+ * Strings become placeholders of the same length that keep the character classes: upper-case
+ * letters become `A`, other letters `a`, digits `0`, and everything else (spaces, `@`, `.`, `-`)
+ * stays, so `jane@mail.test` becomes `aaaa@aaaa.aaaa` and `DE00 0000` becomes `AA00 0000`. Numbers,
+ * booleans and null are kept: they are usually what made the render go wrong, and they rarely
+ * identify a person. Arrays and objects keep their keys and lengths.
+ *
+ * Paths select what is redacted, from the root of the data: dotted segments (`customer.email`),
+ * `*` for any one key or array item (`customer.*`), and `[]` for every item of an array
+ * (`items[].name`, the same as `items.*.name`). A path that ends on an object or array redacts
+ * everything below it. Without paths (or with an empty list) the whole data set is redacted.
+ */
+export declare function redactData<T>(value: T, paths?: readonly string[]): T;
+/** A placeholder of the same length with the character classes of `text` kept. */
+export declare function redactString(text: string): string;
+/** `items[].name` → `['items', '*', 'name']`; `lines[0].qty` → `['lines', '0', 'qty']`. */
+export declare function parseRedactPath(path: string): string[];

package/types/lib/types/emit-python.d.cts

@@ -0,0 +1,6 @@
+import { type TemplateTypes } from './model.cjs';
+/**
+ * `formfeed_templates.py`: a TypedDict per template and `typed(client)`, whose `renders.create`
+ * overloads check `data` for the known slugs and fall back to the plain signature otherwise.
+ */
+export declare function emitPython(templates: TemplateTypes[]): string;