@formfeed/devkit 0.3.9 → 0.3.11

package/index.cjs

@@ -221,16 +221,23 @@ function readJson(path, what) {
   try {
     return JSON.parse(text2);
   } catch (e) {
-    throw new DevkitError(`${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`, "validation");
+    throw new DevkitError(
+      `${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`,
+      "validation"
+    );
   }
 }
 var templateFileName = (kind) => (0, import_engine2.isOfficeKind)(kind) ? `template.${kind}` : "template.html";
 function sourceFilesIn(dir) {
-  return ["template.html", ...import_engine2.officeKinds.map((k) => `template.${k}`)].filter((name) => (0, import_node_fs2.existsSync)((0, import_node_path2.join)(dir, name)));
+  return ["template.html", ...import_engine2.officeKinds.map((k) => `template.${k}`)].filter(
+    (name) => (0, import_node_fs2.existsSync)((0, import_node_path2.join)(dir, name))
+  );
 }
 function listTemplateSlugs(project) {
   if (!(0, import_node_fs2.existsSync)(project.templatesDir)) return [];
-  return (0, import_node_fs2.readdirSync)(project.templatesDir).filter((name) => sourceFilesIn((0, import_node_path2.join)(project.templatesDir, name)).length > 0).sort();
+  return (0, import_node_fs2.readdirSync)(project.templatesDir).filter(
+    (name) => sourceFilesIn((0, import_node_path2.join)(project.templatesDir, name)).length > 0
+  ).sort();
 }
 function templateDir(project, slug) {
   return (0, import_node_path2.join)(project.templatesDir, slug);
@@ -239,22 +246,41 @@ var sha256Of = (bytes) => (0, import_node_crypto.createHash)("sha256").update(by
 function readOfficeFile(dir, name) {
   const path = (0, import_node_path2.join)(dir, name);
   const bytes = new Uint8Array((0, import_node_fs2.readFileSync)(path));
-  return { format: (0, import_node_path2.extname)(name).slice(1), path, bytes, sha256: sha256Of(bytes) };
+  return {
+    format: (0, import_node_path2.extname)(name).slice(1),
+    path,
+    bytes,
+    sha256: sha256Of(bytes)
+  };
 }
 function readTemplate(project, slug) {
   const dir = templateDir(project, slug);
   const sources = sourceFilesIn(dir);
   if (sources.length === 0)
-    throw new DevkitError(`No template "${slug}" in ${project.templatesDir} (template.html, template.docx or template.pptx missing)`);
+    throw new DevkitError(
+      `No template "${slug}" in ${project.templatesDir} (template.html, template.docx or template.pptx missing)`
+    );
   if (sources.length > 1)
-    throw new DevkitError(`${dir} holds ${sources.join(" and ")}; a template folder has one of them`, "validation");
+    throw new DevkitError(
+      `${dir} holds ${sources.join(" and ")}; a template folder has one of them`,
+      "validation"
+    );
   const file = sources[0] === "template.html" ? null : readOfficeFile(dir, sources[0]);
   const html = file ? "" : readText((0, import_node_path2.join)(dir, "template.html")) ?? "";
-  const metaFile = readJson((0, import_node_path2.join)(dir, "template.json"), "template.json") ?? {};
+  const metaFile = readJson(
+    (0, import_node_path2.join)(dir, "template.json"),
+    "template.json"
+  ) ?? {};
   if (file && metaFile.kind && metaFile.kind !== file.format)
-    throw new DevkitError(`${slug}: template.json says kind "${metaFile.kind}", but the folder holds ${(0, import_node_path2.basename)(file.path)}`, "validation");
+    throw new DevkitError(
+      `${slug}: template.json says kind "${metaFile.kind}", but the folder holds ${(0, import_node_path2.basename)(file.path)}`,
+      "validation"
+    );
   if (!file && (0, import_engine2.isOfficeKind)(metaFile.kind))
-    throw new DevkitError(`${slug}: template.json says kind "${metaFile.kind}", but the folder holds template.html instead of template.${metaFile.kind}`, "validation");
+    throw new DevkitError(
+      `${slug}: template.json says kind "${metaFile.kind}", but the folder holds template.html instead of template.${metaFile.kind}`,
+      "validation"
+    );
   const meta = {
     name: metaFile.name ?? titleFromSlug(slug),
     kind: file?.format ?? metaFile.kind ?? "pdf",
@@ -262,19 +288,38 @@ function readTemplate(project, slug) {
     description: metaFile.description ?? null,
     tags: metaFile.tags ?? []
   };
-  const settings = { ...readJson((0, import_node_path2.join)(dir, "settings.json"), "settings.json") ?? {} };
+  const settings = {
+    ...readJson(
+      (0, import_node_path2.join)(dir, "settings.json"),
+      "settings.json"
+    ) ?? {}
+  };
   const header = file ? null : readText((0, import_node_path2.join)(dir, "header.html"));
   const footer = file ? null : readText((0, import_node_path2.join)(dir, "footer.html"));
-  if (header !== null && header.trim()) settings.header = { ...settings.header ?? {}, html: header };
-  if (footer !== null && footer.trim()) settings.footer = { ...settings.footer ?? {}, html: footer };
+  if (header !== null && header.trim())
+    settings.header = { ...settings.header ?? {}, html: header };
+  if (footer !== null && footer.trim())
+    settings.footer = { ...settings.footer ?? {}, html: footer };
+  const design = readJson(
+    (0, import_node_path2.join)(dir, "design.json"),
+    "design.json"
+  );
+  if (design) settings.design = design;
   const dataSets = {};
   const dataDir = (0, import_node_path2.join)(dir, "data");
   if ((0, import_node_fs2.existsSync)(dataDir)) {
     for (const file2 of (0, import_node_fs2.readdirSync)(dataDir).filter((f) => f.endsWith(".json")).sort()) {
-      dataSets[(0, import_node_path2.basename)(file2, ".json")] = readJson((0, import_node_path2.join)(dataDir, file2), `data/${file2}`);
+      dataSets[(0, import_node_path2.basename)(file2, ".json")] = readJson(
+        (0, import_node_path2.join)(dataDir, file2),
+        `data/${file2}`
+      );
     }
   }
-  const { partials, missing, shared } = file ? { partials: {}, missing: [], shared: [] } : collectPartials(project, meta.engine, [html, settings.header?.html, settings.footer?.html]);
+  const { partials, missing, shared } = file ? { partials: {}, missing: [], shared: [] } : collectPartials(project, meta.engine, [
+    html,
+    settings.header?.html,
+    settings.footer?.html
+  ]);
   return {
     slug,
     dir,
@@ -285,8 +330,14 @@ function readTemplate(project, slug) {
     head: file ? "" : readText((0, import_node_path2.join)(dir, "head.html")) ?? "",
     settings,
     dataSets,
-    dataSchema: readJson((0, import_node_path2.join)(dir, "schema.json"), "schema.json"),
-    i18n: readJson((0, import_node_path2.join)(dir, "i18n.json"), "i18n.json"),
+    dataSchema: readJson(
+      (0, import_node_path2.join)(dir, "schema.json"),
+      "schema.json"
+    ),
+    i18n: readJson(
+      (0, import_node_path2.join)(dir, "i18n.json"),
+      "i18n.json"
+    ),
     partials,
     missingPartials: missing,
     sharedPartials: shared
@@ -296,35 +347,68 @@ function defaultData(tpl, name) {
   const names = Object.keys(tpl.dataSets);
   const chosen = name ?? (names.includes("default") ? "default" : names[0]);
   if (name && !(name in tpl.dataSets))
-    throw new DevkitError(`Data set "${name}" not found; available: ${names.join(", ") || "none"}`);
+    throw new DevkitError(
+      `Data set "${name}" not found; available: ${names.join(", ") || "none"}`
+    );
   return chosen ? { name: chosen, data: tpl.dataSets[chosen] } : { name: "empty", data: {} };
 }
 function writeTemplate(project, slug, meta, version, file) {
   const dir = templateDir(project, slug);
   const office = (0, import_engine2.isOfficeKind)(meta.kind);
-  if (office && !file) throw new DevkitError(`${slug} is a ${meta.kind} template; its document is needed to write the folder`);
+  if (office && !file)
+    throw new DevkitError(
+      `${slug} is a ${meta.kind} template; its document is needed to write the folder`
+    );
   (0, import_node_fs2.mkdirSync)((0, import_node_path2.join)(dir, "data"), { recursive: true });
   const settings = { ...version.settings ?? {} };
   const header = office ? "" : settings.header?.html ?? "";
   const footer = office ? "" : settings.footer?.html ?? "";
   if (settings.header) settings.header = stripHtml(settings.header);
   if (settings.footer) settings.footer = stripHtml(settings.footer);
-  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "template.json"), JSON.stringify(meta, null, 2) + "\n");
-  for (const name of ["template.html", ...import_engine2.officeKinds.map((k) => `template.${k}`)])
-    if (name !== templateFileName(meta.kind) && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(dir, name))) (0, import_node_fs2.rmSync)((0, import_node_path2.join)(dir, name));
+  const design = settings.design;
+  delete settings.design;
+  (0, import_node_fs2.writeFileSync)(
+    (0, import_node_path2.join)(dir, "template.json"),
+    JSON.stringify(meta, null, 2) + "\n"
+  );
+  for (const name of [
+    "template.html",
+    ...import_engine2.officeKinds.map((k) => `template.${k}`)
+  ])
+    if (name !== templateFileName(meta.kind) && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(dir, name)))
+      (0, import_node_fs2.rmSync)((0, import_node_path2.join)(dir, name));
   if (office) (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, templateFileName(meta.kind)), file);
   else (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "template.html"), version.html ?? "");
   writeOrRemove((0, import_node_path2.join)(dir, "style.css"), office ? "" : version.css ?? "");
   writeOrRemove((0, import_node_path2.join)(dir, "head.html"), office ? "" : version.head ?? "");
   writeOrRemove((0, import_node_path2.join)(dir, "header.html"), header);
   writeOrRemove((0, import_node_path2.join)(dir, "footer.html"), footer);
-  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
-  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "data", "default.json"), JSON.stringify(version.sample_data ?? {}, null, 2) + "\n");
+  (0, import_node_fs2.writeFileSync)(
+    (0, import_node_path2.join)(dir, "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n"
+  );
+  writeOrRemove(
+    (0, import_node_path2.join)(dir, "design.json"),
+    design && typeof design === "object" ? JSON.stringify(design, null, 2) + "\n" : ""
+  );
+  (0, import_node_fs2.writeFileSync)(
+    (0, import_node_path2.join)(dir, "data", "default.json"),
+    JSON.stringify(version.sample_data ?? {}, null, 2) + "\n"
+  );
   for (const [name, data] of Object.entries(version.data_sets ?? {}))
     if (name !== "default" && /^[\w.-]+$/.test(name))
-      (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "data", `${name}.json`), JSON.stringify(data ?? {}, null, 2) + "\n");
-  writeOrRemove((0, import_node_path2.join)(dir, "schema.json"), version.data_schema ? JSON.stringify(version.data_schema, null, 2) + "\n" : "");
-  writeOrRemove((0, import_node_path2.join)(dir, "i18n.json"), version.i18n ? JSON.stringify(version.i18n, null, 2) + "\n" : "");
+      (0, import_node_fs2.writeFileSync)(
+        (0, import_node_path2.join)(dir, "data", `${name}.json`),
+        JSON.stringify(data ?? {}, null, 2) + "\n"
+      );
+  writeOrRemove(
+    (0, import_node_path2.join)(dir, "schema.json"),
+    version.data_schema ? JSON.stringify(version.data_schema, null, 2) + "\n" : ""
+  );
+  writeOrRemove(
+    (0, import_node_path2.join)(dir, "i18n.json"),
+    version.i18n ? JSON.stringify(version.i18n, null, 2) + "\n" : ""
+  );
   writePartials(project, version.partials ?? null);
   return dir;
 }
@@ -333,7 +417,10 @@ function writePartials(project, partials) {
   const changed = [];
   for (const [name, source] of Object.entries(partials ?? {})) {
     if (!partialName.test(name)) continue;
-    const path = (0, import_node_path2.join)(project.partialsDir, name.includes(".") ? name : `${name}.html`);
+    const path = (0, import_node_path2.join)(
+      project.partialsDir,
+      name.includes(".") ? name : `${name}.html`
+    );
     if (readText(path) === source) continue;
     (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(path), { recursive: true });
     (0, import_node_fs2.writeFileSync)(path, source);
@@ -379,17 +466,36 @@ function versionPayload(tpl) {
 function contentHash(tpl) {
   if (tpl.file) {
     const payload2 = officeVersionPayload(tpl);
-    const parts2 = [tpl.file.format, tpl.file.sha256, payload2.settings, payload2.sample_data, payload2.data_sets, payload2.data_schema, payload2.i18n];
+    const parts2 = [
+      tpl.file.format,
+      tpl.file.sha256,
+      payload2.settings,
+      payload2.sample_data,
+      payload2.data_sets,
+      payload2.data_schema,
+      payload2.i18n
+    ];
     return (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(parts2)).digest("hex");
   }
   const payload = versionPayload(tpl);
-  const parts = [payload.html, payload.css, payload.head, payload.settings, payload.sample_data, payload.data_sets, payload.data_schema, payload.i18n];
+  const parts = [
+    payload.html,
+    payload.css,
+    payload.head,
+    payload.settings,
+    payload.sample_data,
+    payload.data_sets,
+    payload.data_schema,
+    payload.i18n
+  ];
   if (payload.partials) parts.push(payload.partials);
   return (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(parts)).digest("hex");
 }
 var statePath = (project) => (0, import_node_path2.join)(project.root, ".formfeed", "state.json");
 function readState(project) {
-  return readJson(statePath(project), ".formfeed/state.json") ?? { templates: {} };
+  return readJson(statePath(project), ".formfeed/state.json") ?? {
+    templates: {}
+  };
 }
 function writeState(project, state) {
   (0, import_node_fs2.mkdirSync)((0, import_node_path2.join)(project.root, ".formfeed"), { recursive: true });
@@ -415,7 +521,8 @@ function partialResolver(project) {
   return (name) => {
     for (const candidate of [name, `${name}.html`]) {
       const path = (0, import_node_path2.join)(project.partialsDir, candidate);
-      if ((0, import_node_fs2.existsSync)(path) && (0, import_node_fs2.statSync)(path).isFile()) return (0, import_node_fs2.readFileSync)(path, "utf8");
+      if ((0, import_node_fs2.existsSync)(path) && (0, import_node_fs2.statSync)(path).isFile())
+        return (0, import_node_fs2.readFileSync)(path, "utf8");
     }
     shared ??= new Set(Object.keys(readState(project).sharedPartials ?? {}));
     const normalised = (0, import_engine2.normalisePartialName)(name);
@@ -436,7 +543,12 @@ function recordSharedPartial(project, name, remote, source) {
   const state = readState(project);
   state.sharedPartials = {
     ...state.sharedPartials ?? {},
-    [name]: { version: remote.version, engine: remote.engine, contentHash: partialContentHash(source), syncedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    [name]: {
+      version: remote.version,
+      engine: remote.engine,
+      contentHash: partialContentHash(source),
+      syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
   };
   writeState(project, state);
 }
@@ -494,7 +606,10 @@ function diagnose(tpl, sampleData) {
         severity: "error",
         code: "syntax-error",
         message: e.message,
-        range: { start: { line: e.line ?? 1, column: e.column ?? 1 }, end: { line: e.line ?? 1, column: (e.column ?? 1) + 1 } }
+        range: {
+          start: { line: e.line ?? 1, column: e.column ?? 1 },
+          end: { line: e.line ?? 1, column: (e.column ?? 1) + 1 }
+        }
       });
     } else throw e;
   }
@@ -504,7 +619,8 @@ function diagnose(tpl, sampleData) {
     ["footer", tpl.settings.footer?.html]
   ]) {
     if (!source) continue;
-    for (const d of engine.analyze(source, { sampleData }).diagnostics) diagnostics.push({ ...d, message: `${part}: ${d.message}` });
+    for (const d of engine.analyze(source, { sampleData }).diagnostics)
+      diagnostics.push({ ...d, message: `${part}: ${d.message}` });
   }
   for (const name of tpl.missingPartials)
     diagnostics.push({
@@ -514,8 +630,28 @@ function diagnose(tpl, sampleData) {
       message: `No partial "${name}" in the project's partials folder; if it is shared by the organisation, formfeed partials pull brings it`,
       range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } }
     });
+  const design = designDiagnostic(tpl);
+  if (design) diagnostics.push(design);
   return diagnostics;
 }
+function designDiagnostic(tpl) {
+  if (tpl.settings.design === void 0) return null;
+  const parsed = (0, import_engine4.parseDesign)(tpl.settings.design);
+  if (!parsed.design)
+    return {
+      severity: "warning",
+      code: "design-invalid",
+      message: `design.json is not a design the app can open (${parsed.problems.slice(0, 3).join("; ")}); the template opens as code`,
+      range: nowhere
+    };
+  if (parsed.design.output === (0, import_engine4.designOutputHash)(tpl.html, tpl.css)) return null;
+  return {
+    severity: "warning",
+    code: "design-stale",
+    message: "template.html or style.css was edited after design.json was written; the app opens the template as code until you choose to keep the code or apply the design again",
+    range: nowhere
+  };
+}
 var nowhere = { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } };
 function diagnoseOffice(tpl, file, sampleData) {
   let analysis;
@@ -523,7 +659,14 @@ function diagnoseOffice(tpl, file, sampleData) {
     analysis = (0, import_engine4.analyzeOffice)(file, { engine: tpl.meta.engine, sampleData });
   } catch (e) {
     const code = e.code;
-    return [{ severity: "error", code: typeof code === "string" ? code : "office-document-invalid", message: e instanceof Error ? e.message : String(e), range: nowhere }];
+    return [
+      {
+        severity: "error",
+        code: typeof code === "string" ? code : "office-document-invalid",
+        message: e instanceof Error ? e.message : String(e),
+        range: nowhere
+      }
+    ];
   }
   return analysis.diagnostics.map((d) => ({
     severity: d.severity,
@@ -535,17 +678,34 @@ function diagnoseOffice(tpl, file, sampleData) {
   }));
 }
 async function renderOfficeLocal(project, tpl, data, options = {}) {
-  if (!tpl.file) throw new DevkitError(`${tpl.slug} is not a Word or PowerPoint template`, "validation");
-  const context = renderContext(project, tpl, options.assetBaseUrl, options.brand);
+  if (!tpl.file)
+    throw new DevkitError(
+      `${tpl.slug} is not a Word or PowerPoint template`,
+      "validation"
+    );
+  const context = renderContext(
+    project,
+    tpl,
+    options.assetBaseUrl,
+    options.brand
+  );
   if (options.locale) context.locale = options.locale;
-  return (0, import_engine4.renderOffice)(tpl.file.bytes, { engine: tpl.meta.engine, data, context, images: options.images, random: options.random });
+  return (0, import_engine4.renderOffice)(tpl.file.bytes, {
+    engine: tpl.meta.engine,
+    data,
+    context,
+    images: options.images,
+    random: options.random
+  });
 }
 function htmlSnapshot(rendered) {
   let snapshot = rendered.document;
-  if (rendered.headerHtml) snapshot += `
+  if (rendered.headerHtml)
+    snapshot += `
 <!-- formfeed:header -->
 ${rendered.headerHtml}`;
-  if (rendered.footerHtml) snapshot += `
+  if (rendered.footerHtml)
+    snapshot += `
 <!-- formfeed:footer -->
 ${rendered.footerHtml}`;
   return snapshot;
@@ -598,7 +758,14 @@ async function renderLocal(project, tpl, data, options) {
   const ctx = renderContext(project, tpl, options.assetBaseUrl, options.brand);
   if (options.locale) ctx.locale = options.locale;
   return (0, import_engine4.renderVersion)(
-    { engine: tpl.meta.engine, html: tpl.html, css: tpl.css, head: tpl.head, settings: (0, import_engine4.mergeSettings)(tpl.settings), kind },
+    {
+      engine: tpl.meta.engine,
+      html: tpl.html,
+      css: tpl.css,
+      head: tpl.head,
+      settings: (0, import_engine4.mergeSettings)(tpl.settings),
+      kind
+    },
     data,
     ctx,
     options.mode,
@@ -608,16 +775,26 @@ async function renderLocal(project, tpl, data, options) {
 function renderedSettings(rendered) {
   const style = rendered.inlineCss ? `<style>${rendered.inlineCss}</style>` : "";
   const part = (settings2, html) => settings2?.html ? { ...settings2, html: `${style}${html ?? ""}` } : settings2;
-  const { settings } = rendered;
+  const { design: _design, ...settings } = rendered.settings;
+  void _design;
   return {
     ...settings,
     ...settings.header ? { header: part(settings.header, rendered.headerHtml) } : {},
     ...settings.footer ? { footer: part(settings.footer, rendered.footerHtml) } : {},
-    ...settings.pdf?.metadata?.title !== void 0 ? { pdf: { ...settings.pdf, metadata: { ...settings.pdf.metadata, title: rendered.title ?? "" } } } : {}
+    ...settings.pdf?.metadata?.title !== void 0 ? {
+      pdf: {
+        ...settings.pdf,
+        metadata: { ...settings.pdf.metadata, title: rendered.title ?? "" }
+      }
+    } : {}
   };
 }
 function htmlKind(tpl) {
-  if ((0, import_engine4.isOfficeKind)(tpl.meta.kind)) throw new DevkitError(`${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`, "validation");
+  if ((0, import_engine4.isOfficeKind)(tpl.meta.kind))
+    throw new DevkitError(
+      `${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`,
+      "validation"
+    );
   return tpl.meta.kind;
 }
 function previewDocument(tpl, rendered, mode, pagedScriptUrl) {

package/index.js

@@ -95,7 +95,15 @@ function writeProjectConfig(root, config) {
 
 // packages/devkit/src/lib/project.ts
 import { createHash } from "node:crypto";
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, readdirSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
 import { basename, dirname as dirname2, extname, join as join2 } from "node:path";
 import {
   isOfficeKind,
@@ -149,16 +157,23 @@ function readJson(path, what) {
   try {
     return JSON.parse(text2);
   } catch (e) {
-    throw new DevkitError(`${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`, "validation");
+    throw new DevkitError(
+      `${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`,
+      "validation"
+    );
   }
 }
 var templateFileName = (kind) => isOfficeKind(kind) ? `template.${kind}` : "template.html";
 function sourceFilesIn(dir) {
-  return ["template.html", ...officeKinds.map((k) => `template.${k}`)].filter((name) => existsSync2(join2(dir, name)));
+  return ["template.html", ...officeKinds.map((k) => `template.${k}`)].filter(
+    (name) => existsSync2(join2(dir, name))
+  );
 }
 function listTemplateSlugs(project) {
   if (!existsSync2(project.templatesDir)) return [];
-  return readdirSync(project.templatesDir).filter((name) => sourceFilesIn(join2(project.templatesDir, name)).length > 0).sort();
+  return readdirSync(project.templatesDir).filter(
+    (name) => sourceFilesIn(join2(project.templatesDir, name)).length > 0
+  ).sort();
 }
 function templateDir(project, slug) {
   return join2(project.templatesDir, slug);
@@ -167,22 +182,41 @@ var sha256Of = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function readOfficeFile(dir, name) {
   const path = join2(dir, name);
   const bytes = new Uint8Array(readFileSync2(path));
-  return { format: extname(name).slice(1), path, bytes, sha256: sha256Of(bytes) };
+  return {
+    format: extname(name).slice(1),
+    path,
+    bytes,
+    sha256: sha256Of(bytes)
+  };
 }
 function readTemplate(project, slug) {
   const dir = templateDir(project, slug);
   const sources = sourceFilesIn(dir);
   if (sources.length === 0)
-    throw new DevkitError(`No template "${slug}" in ${project.templatesDir} (template.html, template.docx or template.pptx missing)`);
+    throw new DevkitError(
+      `No template "${slug}" in ${project.templatesDir} (template.html, template.docx or template.pptx missing)`
+    );
   if (sources.length > 1)
-    throw new DevkitError(`${dir} holds ${sources.join(" and ")}; a template folder has one of them`, "validation");
+    throw new DevkitError(
+      `${dir} holds ${sources.join(" and ")}; a template folder has one of them`,
+      "validation"
+    );
   const file = sources[0] === "template.html" ? null : readOfficeFile(dir, sources[0]);
   const html = file ? "" : readText(join2(dir, "template.html")) ?? "";
-  const metaFile = readJson(join2(dir, "template.json"), "template.json") ?? {};
+  const metaFile = readJson(
+    join2(dir, "template.json"),
+    "template.json"
+  ) ?? {};
   if (file && metaFile.kind && metaFile.kind !== file.format)
-    throw new DevkitError(`${slug}: template.json says kind "${metaFile.kind}", but the folder holds ${basename(file.path)}`, "validation");
+    throw new DevkitError(
+      `${slug}: template.json says kind "${metaFile.kind}", but the folder holds ${basename(file.path)}`,
+      "validation"
+    );
   if (!file && isOfficeKind(metaFile.kind))
-    throw new DevkitError(`${slug}: template.json says kind "${metaFile.kind}", but the folder holds template.html instead of template.${metaFile.kind}`, "validation");
+    throw new DevkitError(
+      `${slug}: template.json says kind "${metaFile.kind}", but the folder holds template.html instead of template.${metaFile.kind}`,
+      "validation"
+    );
   const meta = {
     name: metaFile.name ?? titleFromSlug(slug),
     kind: file?.format ?? metaFile.kind ?? "pdf",
@@ -190,19 +224,38 @@ function readTemplate(project, slug) {
     description: metaFile.description ?? null,
     tags: metaFile.tags ?? []
   };
-  const settings = { ...readJson(join2(dir, "settings.json"), "settings.json") ?? {} };
+  const settings = {
+    ...readJson(
+      join2(dir, "settings.json"),
+      "settings.json"
+    ) ?? {}
+  };
   const header = file ? null : readText(join2(dir, "header.html"));
   const footer = file ? null : readText(join2(dir, "footer.html"));
-  if (header !== null && header.trim()) settings.header = { ...settings.header ?? {}, html: header };
-  if (footer !== null && footer.trim()) settings.footer = { ...settings.footer ?? {}, html: footer };
+  if (header !== null && header.trim())
+    settings.header = { ...settings.header ?? {}, html: header };
+  if (footer !== null && footer.trim())
+    settings.footer = { ...settings.footer ?? {}, html: footer };
+  const design = readJson(
+    join2(dir, "design.json"),
+    "design.json"
+  );
+  if (design) settings.design = design;
   const dataSets = {};
   const dataDir = join2(dir, "data");
   if (existsSync2(dataDir)) {
     for (const file2 of readdirSync(dataDir).filter((f) => f.endsWith(".json")).sort()) {
-      dataSets[basename(file2, ".json")] = readJson(join2(dataDir, file2), `data/${file2}`);
+      dataSets[basename(file2, ".json")] = readJson(
+        join2(dataDir, file2),
+        `data/${file2}`
+      );
     }
   }
-  const { partials, missing, shared } = file ? { partials: {}, missing: [], shared: [] } : collectPartials(project, meta.engine, [html, settings.header?.html, settings.footer?.html]);
+  const { partials, missing, shared } = file ? { partials: {}, missing: [], shared: [] } : collectPartials(project, meta.engine, [
+    html,
+    settings.header?.html,
+    settings.footer?.html
+  ]);
   return {
     slug,
     dir,
@@ -213,8 +266,14 @@ function readTemplate(project, slug) {
     head: file ? "" : readText(join2(dir, "head.html")) ?? "",
     settings,
     dataSets,
-    dataSchema: readJson(join2(dir, "schema.json"), "schema.json"),
-    i18n: readJson(join2(dir, "i18n.json"), "i18n.json"),
+    dataSchema: readJson(
+      join2(dir, "schema.json"),
+      "schema.json"
+    ),
+    i18n: readJson(
+      join2(dir, "i18n.json"),
+      "i18n.json"
+    ),
     partials,
     missingPartials: missing,
     sharedPartials: shared
@@ -224,35 +283,68 @@ function defaultData(tpl, name) {
   const names = Object.keys(tpl.dataSets);
   const chosen = name ?? (names.includes("default") ? "default" : names[0]);
   if (name && !(name in tpl.dataSets))
-    throw new DevkitError(`Data set "${name}" not found; available: ${names.join(", ") || "none"}`);
+    throw new DevkitError(
+      `Data set "${name}" not found; available: ${names.join(", ") || "none"}`
+    );
   return chosen ? { name: chosen, data: tpl.dataSets[chosen] } : { name: "empty", data: {} };
 }
 function writeTemplate(project, slug, meta, version, file) {
   const dir = templateDir(project, slug);
   const office = isOfficeKind(meta.kind);
-  if (office && !file) throw new DevkitError(`${slug} is a ${meta.kind} template; its document is needed to write the folder`);
+  if (office && !file)
+    throw new DevkitError(
+      `${slug} is a ${meta.kind} template; its document is needed to write the folder`
+    );
   mkdirSync(join2(dir, "data"), { recursive: true });
   const settings = { ...version.settings ?? {} };
   const header = office ? "" : settings.header?.html ?? "";
   const footer = office ? "" : settings.footer?.html ?? "";
   if (settings.header) settings.header = stripHtml(settings.header);
   if (settings.footer) settings.footer = stripHtml(settings.footer);
-  writeFileSync2(join2(dir, "template.json"), JSON.stringify(meta, null, 2) + "\n");
-  for (const name of ["template.html", ...officeKinds.map((k) => `template.${k}`)])
-    if (name !== templateFileName(meta.kind) && existsSync2(join2(dir, name))) rmSync(join2(dir, name));
+  const design = settings.design;
+  delete settings.design;
+  writeFileSync2(
+    join2(dir, "template.json"),
+    JSON.stringify(meta, null, 2) + "\n"
+  );
+  for (const name of [
+    "template.html",
+    ...officeKinds.map((k) => `template.${k}`)
+  ])
+    if (name !== templateFileName(meta.kind) && existsSync2(join2(dir, name)))
+      rmSync(join2(dir, name));
   if (office) writeFileSync2(join2(dir, templateFileName(meta.kind)), file);
   else writeFileSync2(join2(dir, "template.html"), version.html ?? "");
   writeOrRemove(join2(dir, "style.css"), office ? "" : version.css ?? "");
   writeOrRemove(join2(dir, "head.html"), office ? "" : version.head ?? "");
   writeOrRemove(join2(dir, "header.html"), header);
   writeOrRemove(join2(dir, "footer.html"), footer);
-  writeFileSync2(join2(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
-  writeFileSync2(join2(dir, "data", "default.json"), JSON.stringify(version.sample_data ?? {}, null, 2) + "\n");
+  writeFileSync2(
+    join2(dir, "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n"
+  );
+  writeOrRemove(
+    join2(dir, "design.json"),
+    design && typeof design === "object" ? JSON.stringify(design, null, 2) + "\n" : ""
+  );
+  writeFileSync2(
+    join2(dir, "data", "default.json"),
+    JSON.stringify(version.sample_data ?? {}, null, 2) + "\n"
+  );
   for (const [name, data] of Object.entries(version.data_sets ?? {}))
     if (name !== "default" && /^[\w.-]+$/.test(name))
-      writeFileSync2(join2(dir, "data", `${name}.json`), JSON.stringify(data ?? {}, null, 2) + "\n");
-  writeOrRemove(join2(dir, "schema.json"), version.data_schema ? JSON.stringify(version.data_schema, null, 2) + "\n" : "");
-  writeOrRemove(join2(dir, "i18n.json"), version.i18n ? JSON.stringify(version.i18n, null, 2) + "\n" : "");
+      writeFileSync2(
+        join2(dir, "data", `${name}.json`),
+        JSON.stringify(data ?? {}, null, 2) + "\n"
+      );
+  writeOrRemove(
+    join2(dir, "schema.json"),
+    version.data_schema ? JSON.stringify(version.data_schema, null, 2) + "\n" : ""
+  );
+  writeOrRemove(
+    join2(dir, "i18n.json"),
+    version.i18n ? JSON.stringify(version.i18n, null, 2) + "\n" : ""
+  );
   writePartials(project, version.partials ?? null);
   return dir;
 }
@@ -261,7 +353,10 @@ function writePartials(project, partials) {
   const changed = [];
   for (const [name, source] of Object.entries(partials ?? {})) {
     if (!partialName.test(name)) continue;
-    const path = join2(project.partialsDir, name.includes(".") ? name : `${name}.html`);
+    const path = join2(
+      project.partialsDir,
+      name.includes(".") ? name : `${name}.html`
+    );
     if (readText(path) === source) continue;
     mkdirSync(dirname2(path), { recursive: true });
     writeFileSync2(path, source);
@@ -307,17 +402,36 @@ function versionPayload(tpl) {
 function contentHash(tpl) {
   if (tpl.file) {
     const payload2 = officeVersionPayload(tpl);
-    const parts2 = [tpl.file.format, tpl.file.sha256, payload2.settings, payload2.sample_data, payload2.data_sets, payload2.data_schema, payload2.i18n];
+    const parts2 = [
+      tpl.file.format,
+      tpl.file.sha256,
+      payload2.settings,
+      payload2.sample_data,
+      payload2.data_sets,
+      payload2.data_schema,
+      payload2.i18n
+    ];
     return createHash("sha256").update(JSON.stringify(parts2)).digest("hex");
   }
   const payload = versionPayload(tpl);
-  const parts = [payload.html, payload.css, payload.head, payload.settings, payload.sample_data, payload.data_sets, payload.data_schema, payload.i18n];
+  const parts = [
+    payload.html,
+    payload.css,
+    payload.head,
+    payload.settings,
+    payload.sample_data,
+    payload.data_sets,
+    payload.data_schema,
+    payload.i18n
+  ];
   if (payload.partials) parts.push(payload.partials);
   return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
 }
 var statePath = (project) => join2(project.root, ".formfeed", "state.json");
 function readState(project) {
-  return readJson(statePath(project), ".formfeed/state.json") ?? { templates: {} };
+  return readJson(statePath(project), ".formfeed/state.json") ?? {
+    templates: {}
+  };
 }
 function writeState(project, state) {
   mkdirSync(join2(project.root, ".formfeed"), { recursive: true });
@@ -343,7 +457,8 @@ function partialResolver(project) {
   return (name) => {
     for (const candidate of [name, `${name}.html`]) {
       const path = join2(project.partialsDir, candidate);
-      if (existsSync2(path) && statSync(path).isFile()) return readFileSync2(path, "utf8");
+      if (existsSync2(path) && statSync(path).isFile())
+        return readFileSync2(path, "utf8");
     }
     shared ??= new Set(Object.keys(readState(project).sharedPartials ?? {}));
     const normalised = normalisePartialName2(name);
@@ -364,7 +479,12 @@ function recordSharedPartial(project, name, remote, source) {
   const state = readState(project);
   state.sharedPartials = {
     ...state.sharedPartials ?? {},
-    [name]: { version: remote.version, engine: remote.engine, contentHash: partialContentHash(source), syncedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    [name]: {
+      version: remote.version,
+      engine: remote.engine,
+      contentHash: partialContentHash(source),
+      syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
   };
   writeState(project, state);
 }
@@ -414,12 +534,14 @@ import {
   analyzeOffice,
   defaultHelpers,
   defaultLimits,
+  designOutputHash,
   flowDocument,
   getEngine as getEngine2,
   isOfficeKind as isOfficeKind2,
   mergeSettings,
   officeTextParts,
   pagedDocument,
+  parseDesign,
   renderOffice,
   renderVersion
 } from "@formfeed/engine";
@@ -435,7 +557,10 @@ function diagnose(tpl, sampleData) {
         severity: "error",
         code: "syntax-error",
         message: e.message,
-        range: { start: { line: e.line ?? 1, column: e.column ?? 1 }, end: { line: e.line ?? 1, column: (e.column ?? 1) + 1 } }
+        range: {
+          start: { line: e.line ?? 1, column: e.column ?? 1 },
+          end: { line: e.line ?? 1, column: (e.column ?? 1) + 1 }
+        }
       });
     } else throw e;
   }
@@ -445,7 +570,8 @@ function diagnose(tpl, sampleData) {
     ["footer", tpl.settings.footer?.html]
   ]) {
     if (!source) continue;
-    for (const d of engine.analyze(source, { sampleData }).diagnostics) diagnostics.push({ ...d, message: `${part}: ${d.message}` });
+    for (const d of engine.analyze(source, { sampleData }).diagnostics)
+      diagnostics.push({ ...d, message: `${part}: ${d.message}` });
   }
   for (const name of tpl.missingPartials)
     diagnostics.push({
@@ -455,8 +581,28 @@ function diagnose(tpl, sampleData) {
       message: `No partial "${name}" in the project's partials folder; if it is shared by the organisation, formfeed partials pull brings it`,
       range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } }
     });
+  const design = designDiagnostic(tpl);
+  if (design) diagnostics.push(design);
   return diagnostics;
 }
+function designDiagnostic(tpl) {
+  if (tpl.settings.design === void 0) return null;
+  const parsed = parseDesign(tpl.settings.design);
+  if (!parsed.design)
+    return {
+      severity: "warning",
+      code: "design-invalid",
+      message: `design.json is not a design the app can open (${parsed.problems.slice(0, 3).join("; ")}); the template opens as code`,
+      range: nowhere
+    };
+  if (parsed.design.output === designOutputHash(tpl.html, tpl.css)) return null;
+  return {
+    severity: "warning",
+    code: "design-stale",
+    message: "template.html or style.css was edited after design.json was written; the app opens the template as code until you choose to keep the code or apply the design again",
+    range: nowhere
+  };
+}
 var nowhere = { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } };
 function diagnoseOffice(tpl, file, sampleData) {
   let analysis;
@@ -464,7 +610,14 @@ function diagnoseOffice(tpl, file, sampleData) {
     analysis = analyzeOffice(file, { engine: tpl.meta.engine, sampleData });
   } catch (e) {
     const code = e.code;
-    return [{ severity: "error", code: typeof code === "string" ? code : "office-document-invalid", message: e instanceof Error ? e.message : String(e), range: nowhere }];
+    return [
+      {
+        severity: "error",
+        code: typeof code === "string" ? code : "office-document-invalid",
+        message: e instanceof Error ? e.message : String(e),
+        range: nowhere
+      }
+    ];
   }
   return analysis.diagnostics.map((d) => ({
     severity: d.severity,
@@ -476,17 +629,34 @@ function diagnoseOffice(tpl, file, sampleData) {
   }));
 }
 async function renderOfficeLocal(project, tpl, data, options = {}) {
-  if (!tpl.file) throw new DevkitError(`${tpl.slug} is not a Word or PowerPoint template`, "validation");
-  const context = renderContext(project, tpl, options.assetBaseUrl, options.brand);
+  if (!tpl.file)
+    throw new DevkitError(
+      `${tpl.slug} is not a Word or PowerPoint template`,
+      "validation"
+    );
+  const context = renderContext(
+    project,
+    tpl,
+    options.assetBaseUrl,
+    options.brand
+  );
   if (options.locale) context.locale = options.locale;
-  return renderOffice(tpl.file.bytes, { engine: tpl.meta.engine, data, context, images: options.images, random: options.random });
+  return renderOffice(tpl.file.bytes, {
+    engine: tpl.meta.engine,
+    data,
+    context,
+    images: options.images,
+    random: options.random
+  });
 }
 function htmlSnapshot(rendered) {
   let snapshot = rendered.document;
-  if (rendered.headerHtml) snapshot += `
+  if (rendered.headerHtml)
+    snapshot += `
 <!-- formfeed:header -->
 ${rendered.headerHtml}`;
-  if (rendered.footerHtml) snapshot += `
+  if (rendered.footerHtml)
+    snapshot += `
 <!-- formfeed:footer -->
 ${rendered.footerHtml}`;
   return snapshot;
@@ -539,7 +709,14 @@ async function renderLocal(project, tpl, data, options) {
   const ctx = renderContext(project, tpl, options.assetBaseUrl, options.brand);
   if (options.locale) ctx.locale = options.locale;
   return renderVersion(
-    { engine: tpl.meta.engine, html: tpl.html, css: tpl.css, head: tpl.head, settings: mergeSettings(tpl.settings), kind },
+    {
+      engine: tpl.meta.engine,
+      html: tpl.html,
+      css: tpl.css,
+      head: tpl.head,
+      settings: mergeSettings(tpl.settings),
+      kind
+    },
     data,
     ctx,
     options.mode,
@@ -549,16 +726,26 @@ async function renderLocal(project, tpl, data, options) {
 function renderedSettings(rendered) {
   const style = rendered.inlineCss ? `<style>${rendered.inlineCss}</style>` : "";
   const part = (settings2, html) => settings2?.html ? { ...settings2, html: `${style}${html ?? ""}` } : settings2;
-  const { settings } = rendered;
+  const { design: _design, ...settings } = rendered.settings;
+  void _design;
   return {
     ...settings,
     ...settings.header ? { header: part(settings.header, rendered.headerHtml) } : {},
     ...settings.footer ? { footer: part(settings.footer, rendered.footerHtml) } : {},
-    ...settings.pdf?.metadata?.title !== void 0 ? { pdf: { ...settings.pdf, metadata: { ...settings.pdf.metadata, title: rendered.title ?? "" } } } : {}
+    ...settings.pdf?.metadata?.title !== void 0 ? {
+      pdf: {
+        ...settings.pdf,
+        metadata: { ...settings.pdf.metadata, title: rendered.title ?? "" }
+      }
+    } : {}
   };
 }
 function htmlKind(tpl) {
-  if (isOfficeKind2(tpl.meta.kind)) throw new DevkitError(`${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`, "validation");
+  if (isOfficeKind2(tpl.meta.kind))
+    throw new DevkitError(
+      `${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`,
+      "validation"
+    );
   return tpl.meta.kind;
 }
 function previewDocument(tpl, rendered, mode, pagedScriptUrl) {

package/package.json

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

package/types/lib/project.d.cts

@@ -5,7 +5,8 @@ import type { Project } from './project-config.cjs';
  * The template folder of spec 15 §2. `template.json` (name, kind, engine, description, tags) is
  * the one addition to the spec's layout: `push` needs it to create a template that does not exist
  * remotely, `pull` writes it. Header and footer live in their own files and fold back into
- * `settings.header.html` / `settings.footer.html`, as the editor's tabs do.
+ * `settings.header.html` / `settings.footer.html`, as the editor's tabs do; a visual design lives in
+ * `design.json` and folds back into `settings.design`.
  */
 export interface TemplateMeta {
     name: string;

package/types/lib/project.d.ts

@@ -5,7 +5,8 @@ import type { Project } from './project-config.js';
  * The template folder of spec 15 §2. `template.json` (name, kind, engine, description, tags) is
  * the one addition to the spec's layout: `push` needs it to create a template that does not exist
  * remotely, `pull` writes it. Header and footer live in their own files and fold back into
- * `settings.header.html` / `settings.footer.html`, as the editor's tabs do.
+ * `settings.header.html` / `settings.footer.html`, as the editor's tabs do; a visual design lives in
+ * `design.json` and folds back into `settings.design`.
  */
 export interface TemplateMeta {
     name: string;