@ham2k/extension-sdk 0.3.0 → 0.4.0

package/README.md

@@ -53,6 +53,26 @@ offline and describe the version installed here rather than whatever the
 repository says today. If an agent is writing your extension, point it at
 `node_modules/@ham2k/extension-sdk/AGENTS.md` — `h2kext-init` does that for you.
 
+## Export types and settings
+
+Export hooks can register shared types with `getExportTypes()`. Use
+`exportTypeDefinition(activationType, format, label)` for an identity shared
+by extensions serving the same activity. `exportType` identifies the settings;
+`exportKey` identifies an individual file, such as one park in an activation.
+
+The `activityExportHook` and `huntingExportHook` helpers register their types
+and forward export settings to the ADIF generator. Reference activity types
+use `templateCategory: 'reference'`; other types use the other-activity defaults.
+`GlobalExportSettings` provides separate normal filename, compact filename,
+and title templates for each category, plus shared ADIF field templates.
+
+When updating an exporter from SDK 0.3, keep a reference-specific identifier
+in `exportKey`, register a stable `exportType`, and forward `exportSettings`,
+`exportData`, `exportTitle`, and `includeLookupData` when delegating generation.
+Per-type custom templates override inherited defaults only when enabled.
+See `docs/hooks.md` §`export` for the complete contract and `docs/forms.md`
+for the `textTemplate` form field.
+
 ## About the peer dependencies
 
 This package lists the libraries the extension host carries — `@ham2k/lib-*`,

package/dist/activityExports.js

@@ -1,3 +1,4 @@
+import { exportTypeDefinition } from "./exportSettings.js";
 import { exportFilename, startMillisOf } from "./exportNames.js";
 import { segmentsWith } from "./segments.js";
 import { createCachedTranslator } from "./i18n.js";
@@ -21,11 +22,23 @@ function filenameFor(operation, qsos, ref, compact) {
 function activityExportHook(rules) {
   const prefix = `${rules.key}-adif`;
   return {
+    async getExportTypes() {
+      return [{
+        ...exportTypeDefinition(rules.activationType, "adif", rules.label),
+        templateCategory: "reference",
+        templateSample: rules.templateSample ?? {
+          log: { ref: "REF-1234", refName: "Example Reference" },
+          operation: { refs: [{ type: rules.activationType, ref: "REF-1234" }] }
+        }
+      }];
+    },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       const refs = refsOfType(operation, rules.activationType);
       const t = tFor(ctx);
       return refs.map((ref) => ({
-        exportType: `${prefix}${SEPARATOR}${ref.ref}`,
+        exportType: `${rules.activationType}-adif`,
+        templateData: { ref: ref.ref, refName: ref.name ?? "", activity: rules.label },
+        exportKey: `${prefix}${SEPARATOR}${ref.ref}`,
         format: "adif",
         // The FORMAT leads: a park activated on a contest weekend offers
         // several files for the same reference, and "POTA US-1234" alone said
@@ -44,10 +57,11 @@ function activityExportHook(rules) {
     },
     async generateExport(args, ctx) {
       const exportType = String(args.exportType ?? "");
-      if (!exportType.startsWith(`${prefix}${SEPARATOR}`)) {
-        throw new Error(`${rules.key}: unknown export type '${exportType}'`);
+      const exportKey = String(args.exportKey ?? "");
+      if (exportType !== `${rules.activationType}-adif` || !exportKey.startsWith(`${prefix}${SEPARATOR}`)) {
+        throw new Error(`${rules.key}: unknown export type/key '${exportType}' / '${exportKey}'`);
       }
-      const wanted = exportType.slice(prefix.length + SEPARATOR.length);
+      const wanted = exportKey.slice(prefix.length + SEPARATOR.length);
       if (!refsOfType(args.operation, rules.activationType).some((r) => r.ref === wanted)) {
         throw new Error(`${rules.key}: operation has no ${rules.activationType} reference '${wanted}'`);
       }
@@ -62,6 +76,10 @@ function activityExportHook(rules) {
         qsos: args.qsos,
         segments: segmentsWith(args.segments, claimOnly),
         includePrivateData: args.includePrivateData,
+        includeLookupData: args.includeLookupData,
+        exportSettings: args.exportSettings,
+        exportData: args.exportData,
+        exportTitle: args.exportTitle,
         mainHandler: rules.key,
         includeFieldsFrom: rules.includeFieldsFrom
       });
@@ -83,17 +101,22 @@ function filenameForHunt(operation, qsos, activity, compact) {
   });
 }
 function huntingExportHook(rules) {
-  const exportType = `${rules.key}-hunter`;
+  const exportType = `${rules.huntingType}-hunter`;
   function huntedQsos(qsos) {
     return qsos.filter((qso) => refsOfType(qso, rules.huntingType).length > 0);
   }
   return {
+    async getExportTypes() {
+      return [{ exportType, format: "adif", label: `${rules.label} Hunter Log` }];
+    },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       if (refsOfType(operation, rules.activationType).length > 0) return [];
       if (huntedQsos(qsos ?? []).length === 0) return [];
       const t = tFor(ctx);
       return [{
         exportType,
+        qsoCount: huntedQsos(qsos ?? []).length,
+        templateData: { activity: rules.label },
         format: "adif",
         label: t("adifForHunter", { program: rules.label }),
         filename: filenameForHunt(operation, qsos ?? [], rules.label, compactFilenames),
@@ -119,6 +142,10 @@ function huntingExportHook(rules) {
         qsos: huntedQsos(args.qsos ?? []),
         segments: args.segments,
         includePrivateData: args.includePrivateData,
+        includeLookupData: args.includeLookupData,
+        exportSettings: args.exportSettings,
+        exportData: args.exportData,
+        exportTitle: args.exportTitle,
         // The hunter file is submitted to ONE program too — see
         // `activityExportHook.generateExport`. `rules.key` is the ACTIVITY's
         // key ('pota'), which is what its `adifFields` hook registers under;
@@ -136,7 +163,7 @@ function huntingExportHook(rules) {
     }
   };
 }
-async function adifForExport({ operation, qsos, segments, includePrivateData, mainHandler, includeFieldsFrom }) {
+async function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }) {
   const { hooks } = await import("@ham2k/extension-sdk");
   const entries = await hooks.invokeOne("export", "adif", "generateExport", {
     operation,
@@ -146,6 +173,10 @@ async function adifForExport({ operation, qsos, segments, includePrivateData, ma
     // Forwarded, or the delegate defaults to withholding and the user's
     // "include private info" setting silently does nothing here.
     includePrivateData,
+    includeLookupData,
+    exportSettings,
+    exportData,
+    exportTitle,
     mainHandler,
     includeFieldsFrom
   });

package/dist/exportSettings.js

@@ -0,0 +1,133 @@
+import { startMillisOf } from "./exportNames.js";
+import { templateContext } from "./templateContext.js";
+import { oneLine, renderTemplate } from "./templates.js";
+import { isTestOperation } from "./testOperation.js";
+const EXPORT_DEFAULTS = {
+  includePrivateData: false,
+  includeLookupData: true,
+  customTemplates: false,
+  filenameTemplate: "{{ op.date }} {{ log.station }}{% if log.ref != blank %} at {{ log.ref }}{% elsif log.activity != blank %} for {{ log.activity }}{% endif %} {{ log.modifier }}",
+  compactFilenameTemplate: "{{ log.station | dash }}{% if log.ref != blank %}@{{ log.ref | dash }}{% elsif log.activity != blank %}-{{ log.activity | downcase | dash }}{% endif %}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  titleTemplate: "{{ log.station }}{% if log.ref != blank %}: {{ log.activity }} at {{ log.ref }} {{ log.refName }}{% elsif log.activity != blank %}: {{ log.activity }}{% endif %} on {{ op.date }}",
+  adifNotesTemplate: "{{ qso.notes }}",
+  adifCommentTemplate: "{{ qso.notes }}",
+  adifQslMessageTemplate: ""
+};
+const GLOBAL_EXPORT_DEFAULTS = {
+  ...EXPORT_DEFAULTS,
+  referenceFilenameTemplate: "{{ op.date }} {{ log.station }} at {{ log.ref }} {{ log.modifier }}",
+  referenceCompactFilenameTemplate: "{{ log.station | dash }}@{{ log.ref | dash }}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  referenceTitleTemplate: "{{ log.station }}: {{ log.activity }} at {{ log.ref }} {{ log.refName }} on {{ op.date }}",
+  otherFilenameTemplate: "{{ op.date }} {{ log.station }}{% if log.activity != blank %} for {{ log.activity }}{% endif %} {{ log.modifier }}",
+  otherCompactFilenameTemplate: "{{ log.station | dash }}{% if log.activity != blank %}-{{ log.activity | downcase | dash }}{% endif %}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  otherTitleTemplate: "{{ log.station }}{% if log.activity != blank %}: {{ log.activity }}{% endif %} on {{ op.date }}"
+};
+function resolveGlobalExportSettings(global = {}) {
+  const resolved = { ...GLOBAL_EXPORT_DEFAULTS, ...global };
+  for (const prefix of ["reference", "other"]) {
+    for (const suffix of ["FilenameTemplate", "CompactFilenameTemplate", "TitleTemplate"]) {
+      const key = `${prefix}${suffix}`;
+      const legacy = `${suffix[0].toLowerCase()}${suffix.slice(1)}`;
+      if (global[key] === void 0 && typeof global[legacy] === "string") {
+        Object.assign(resolved, { [key]: global[legacy] });
+      }
+    }
+  }
+  return resolved;
+}
+function exportTypeDefinition(activationType, format, label, defaults) {
+  return { exportType: `${activationType}-${format}`, activationType, format, label, defaults };
+}
+const templateKeys = [
+  "filenameTemplate",
+  "compactFilenameTemplate",
+  "titleTemplate",
+  "adifNotesTemplate",
+  "adifCommentTemplate",
+  "adifQslMessageTemplate"
+];
+function resolveExportSettings(definition, global = {}, overrides = {}) {
+  const defaults = resolveGlobalExportSettings(global);
+  const reference = definition.templateCategory === "reference";
+  const resolved = {
+    includePrivateData: defaults.includePrivateData,
+    includeLookupData: defaults.includeLookupData,
+    adifNotesTemplate: defaults.adifNotesTemplate,
+    adifCommentTemplate: defaults.adifCommentTemplate,
+    adifQslMessageTemplate: defaults.adifQslMessageTemplate,
+    filenameTemplate: reference ? defaults.referenceFilenameTemplate : defaults.otherFilenameTemplate,
+    compactFilenameTemplate: reference ? defaults.referenceCompactFilenameTemplate : defaults.otherCompactFilenameTemplate,
+    titleTemplate: reference ? defaults.referenceTitleTemplate : defaults.otherTitleTemplate,
+    ...definition.defaults
+  };
+  for (const key of ["includePrivateData", "includeLookupData"]) {
+    if (typeof overrides[key] === "boolean") resolved[key] = overrides[key];
+  }
+  resolved.customTemplates = overrides.customTemplates === true;
+  if (resolved.customTemplates) {
+    for (const key of templateKeys) {
+      if (typeof overrides[key] === "string") resolved[key] = overrides[key];
+    }
+  }
+  if (definition.format !== "adif") {
+    delete resolved.includePrivateData;
+    delete resolved.includeLookupData;
+    for (const key of templateKeys.slice(2)) delete resolved[key];
+  }
+  return resolved;
+}
+function exportQso(qso, settings) {
+  const copy = { ...qso };
+  for (const side of ["their", "our"]) {
+    if (copy[side] && typeof copy[side] === "object" && !Array.isArray(copy[side])) {
+      const station = { ...copy[side] };
+      if (settings.includeLookupData === false) delete station.guess;
+      if (settings.includePrivateData === false) {
+        for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete station[key];
+        if (typeof station.grid === "string") station.grid = station.grid.slice(0, 6);
+        if (station.guess && typeof station.guess === "object") {
+          const guess = { ...station.guess };
+          for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete guess[key];
+          if (typeof guess.grid === "string") guess.grid = guess.grid.slice(0, 6);
+          station.guess = guess;
+        }
+      }
+      copy[side] = station;
+    }
+  }
+  if (settings.includePrivateData === false) delete copy.notes;
+  return copy;
+}
+function prepareExportOption(option, operation, qsos, compact) {
+  const settings = option.exportSettings;
+  const extension = { adif: "adi", cabrillo: "log", reg1test: "edi" }[option.format] ?? option.filename?.split(".").pop() ?? "txt";
+  const data = {
+    station: String(operation.stationCall ?? ""),
+    ref: "",
+    activity: "",
+    modifier: "",
+    ...option.templateData,
+    exportType: option.exportType,
+    format: option.format,
+    extension,
+    compact
+  };
+  if (isTestOperation(operation.stationCall)) data.modifier = [data.modifier, "Testing"].filter(Boolean).join(" ");
+  const context = templateContext({ operation, qsoCount: option.qsoCount ?? qsos.length, atMillis: startMillisOf(operation, qsos) ?? Date.now(), log: data });
+  const template = compact ? settings.compactFilenameTemplate : settings.filenameTemplate;
+  const rendered = oneLine(renderTemplate(template ?? "", context, "Export filename"));
+  const stem = rendered.replace(/[/\\:*?"<>|\x00-\x1f]+/g, "-").replace(/[. ]+$/g, "").trim() || "export";
+  const filename = stem.toLowerCase().endsWith(`.${extension}`) ? stem : `${stem}.${extension}`;
+  const titleContext = settings.includePrivateData === false ? { ...context, op: { ...context.op, title: "", userTitle: "", userNotes: "", grid: String(context.op.grid ?? "").slice(0, 6) }, log: { ...context.log, modifier: "" } } : context;
+  const title = oneLine(renderTemplate(settings.titleTemplate ?? "", titleContext, "Export title"));
+  return { ...option, filename, exportTitle: title, exportData: settings.includePrivateData === false ? { ...data, modifier: "" } : data };
+}
+export {
+  EXPORT_DEFAULTS,
+  GLOBAL_EXPORT_DEFAULTS,
+  exportQso,
+  exportTypeDefinition,
+  prepareExportOption,
+  resolveExportSettings,
+  resolveGlobalExportSettings
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.3.0
+// @ham2k/extension-sdk 0.4.0
 export type CallInfo = {
 	call: string;
 	baseCall?: string;
@@ -388,11 +388,44 @@ export interface AdifImportHook {
 		}[];
 	}, ctx: HookContext): Promise<(AdifImportResult | null)[]>;
 }
+export interface ExportSettings {
+	includePrivateData?: boolean;
+	includeLookupData?: boolean;
+	customTemplates?: boolean;
+	filenameTemplate?: string;
+	compactFilenameTemplate?: string;
+	titleTemplate?: string;
+	adifNotesTemplate?: string;
+	adifCommentTemplate?: string;
+	adifQslMessageTemplate?: string;
+}
+export interface GlobalExportSettings extends ExportSettings {
+	referenceFilenameTemplate?: string;
+	referenceCompactFilenameTemplate?: string;
+	referenceTitleTemplate?: string;
+	otherFilenameTemplate?: string;
+	otherCompactFilenameTemplate?: string;
+	otherTitleTemplate?: string;
+}
+export interface ExportTypeDefinition {
+	exportType: string;
+	label: string;
+	format: string;
+	activationType?: string;
+	templateCategory?: "reference" | "other";
+	defaults?: ExportSettings;
+	templateSample?: Record<string, JSONValue>;
+}
 export interface ExportRequest {
+	exportSettings?: ExportSettings;
+	exportData?: Record<string, JSONValue>;
+	exportTitle?: string;
+	includeLookupData?: boolean;
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
 	exportType?: string;
+	exportKey?: string;
 	compactFilenames?: boolean;
 	includePrivateData?: boolean;
 	mainHandler?: string;
@@ -409,7 +442,10 @@ export interface ExportOptionsRequest {
 	compactFilenames?: boolean;
 }
 export interface ExportOption {
+	qsoCount?: number;
+	templateData?: Record<string, JSONValue>;
 	exportType: string;
+	exportKey?: string;
 	format: string;
 	label: string;
 	filename?: string;
@@ -421,6 +457,7 @@ export interface ExportOption {
 	refType?: string;
 }
 export interface ExportHook {
+	getExportTypes?(args: Record<string, never>, ctx: HookContext): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions?(args: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 }
@@ -871,7 +908,7 @@ export interface DataFileDefinition {
 	onLoadRawData?: (data: any) => void;
 	onRemoveRawData?: () => Promise<void>;
 }
-export type FormFieldType = "text" | "multiline" | "email" | "callsign" | "number" | "select" | "radio" | "checkbox" | "secret" | "list" | "multiselect" | "account";
+export type FormFieldType = "text" | "multiline" | "textTemplate" | "email" | "callsign" | "number" | "select" | "radio" | "checkbox" | "secret" | "list" | "multiselect" | "account";
 export interface FormFieldOption {
 	label: string;
 	value: any;
@@ -885,6 +922,8 @@ export interface FormField {
 	label: string;
 	value?: any;
 	placeholder?: string;
+	templateContext?: "export" | "adif" | "text";
+	templateSample?: Record<string, JSONValue>;
 	uppercase?: boolean;
 	options?: FormFieldOption[] | string;
 	validate?: (value: any, state: Record<string, any>) => string | null | undefined | Promise<string | null | undefined>;
@@ -934,6 +973,8 @@ export interface FormMarkdownBlock {
 	title?: string;
 }
 export interface FormActionElement {
+	style?: "row";
+	icon?: string;
 	type: "action";
 	key: string;
 	label: string;
@@ -1235,12 +1276,14 @@ export type ActivityScoresheet = {
 export declare function activityScorer(rules: ActivityScoringRules): ContestScorer<ActivityScoresheet>;
 export interface ActivityExportRules {
 	key: string;
+	templateSample?: Record<string, JSONValue>;
 	label: string;
 	activationType: string;
 	icon?: string;
 	includeFieldsFrom?: string[];
 }
 export declare function activityExportHook(rules: ActivityExportRules): {
+	getExportTypes(): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
@@ -1254,14 +1297,19 @@ export interface HuntingExportRules {
 	includeFieldsFrom?: string[];
 }
 export declare function huntingExportHook(rules: HuntingExportRules): {
+	getExportTypes(): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
-export declare function adifForExport({ operation, qsos, segments, includePrivateData, mainHandler, includeFieldsFrom }: {
+export declare function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }: {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
 	includePrivateData?: boolean;
+	includeLookupData?: boolean;
+	exportSettings?: ExportSettings;
+	exportData?: Record<string, JSONValue>;
+	exportTitle?: string;
 	mainHandler: string;
 	includeFieldsFrom?: string[];
 }): Promise<string>;
@@ -1284,6 +1332,19 @@ export interface ExportNameParts {
 }
 export declare function exportFilename(parts: ExportNameParts): string;
 export declare function startMillisOf(operation: Record<string, JSONValue>, qsos?: Record<string, JSONValue>[]): number | undefined;
+export declare const EXPORT_DEFAULTS: ExportSettings;
+export declare const GLOBAL_EXPORT_DEFAULTS: GlobalExportSettings;
+export declare function resolveGlobalExportSettings(global?: GlobalExportSettings): GlobalExportSettings;
+export declare function exportTypeDefinition(activationType: string, format: string, label: string, defaults?: ExportSettings): ExportTypeDefinition;
+export declare function resolveExportSettings(definition: ExportTypeDefinition, global?: GlobalExportSettings, overrides?: ExportSettings): ExportSettings;
+export declare function exportQso(qso: Record<string, JSONValue>, settings: ExportSettings): Record<string, JSONValue>;
+export declare function prepareExportOption(option: ExportOption & {
+	exportSettings: ExportSettings;
+}, operation: Record<string, JSONValue>, qsos: Record<string, JSONValue>[], compact: boolean): ExportOption & {
+	exportSettings: ExportSettings;
+	exportTitle: string;
+	exportData: Record<string, JSONValue>;
+};
 export type RefTransform = {
 	pattern: string;
 	replacement: string;

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./activityScoring.js";
 export * from "./activityExports.js";
 export * from "./activityAdifImport.js";
 export * from "./exportNames.js";
+export * from "./exportSettings.js";
 export * from "./referenceActivity.js";
 export * from "./refTransforms.js";
 export * from "./templates.js";

package/docs/forms.md

@@ -14,6 +14,7 @@ All types are defined in `extensions/sdk/src/types.ts`.
 export type FormFieldType =
   | 'text'
   | 'multiline'
+  | 'textTemplate'
   | 'email'
   | 'callsign'
   | 'number'
@@ -70,8 +71,8 @@ export interface FormField {
   // fields — a whole section header can be dev-mode-only too.
   devMode?: boolean;
   // Settings-panel-only (ignored in ad hoc forms) — see settings.md's
-  // "Common Settings and environment gating". Also shows this field on
-  // the app's Common Settings quick-access panel.
+  // "Common Preferences and environment gating". Also shows this field on
+  // the app's Common Preferences quick-access panel.
   common?: boolean;
   // Settings-panel-only. Restricts which platform(s) show this field at
   // all: one or more platform tokens (`ios`, `android`, `macos`,
@@ -129,6 +130,8 @@ export interface FormMarkdownBlock {
 // SDK already permits (see settings.md's settingsPanel note). Not used for
 // account credentials — those have their own testCredentials on AccountHook.
 export interface FormActionElement {
+  style?: 'row'; // icon row with a chevron; omit for a button
+  icon?: string;
   type: 'action';
   key: string;
   label: string;
@@ -277,3 +280,28 @@ api.registerHook('form', {
    - Any validation error returns back to Dart and is displayed underneath the field. If any fields have errors, submission is aborted.
 3. **Submit transformation**: When all fields are successfully validated, Dart invokes any JS transformation callbacks for each field.
 4. **Completion**: The final transformed state is resolved and returned back to the caller (or saved in the view context).
+
+## Text templates
+
+`fieldType: 'textTemplate'` is a string field displayed as an editor row in
+forms and settings. It opens a multiline Liquid editor with a sample preview,
+syntax errors, insertable attributes and flow-control examples, and a read-only
+filter reference inside collapsed Templating Docs. Editing and preview stay
+above the scrollable reference. Template rows also display rendered samples. Save commits
+the draft; Cancel, Escape and dismissal discard it. `defaultValue` supplies
+the Reset button. Disabled fields cannot open the editor.
+
+```ts
+{
+  type: 'field', fieldType: 'textTemplate', key: 'filename',
+  label: 'File name', value: '{{ op.date }} {{ log.station }}',
+  templateContext: 'export', // 'adif' adds contact attributes; 'text' is generic
+  templateSample: { log: { activity: 'POTA', ref: 'US-1234' } },
+}
+```
+
+The preview uses the same runtime and vocabulary as exports; sample values
+are illustrative. `templateSample` can replace values in `operation`, `qso`
+and `log`. The app provides the rendering callback through
+`TemplateEditorScope`, keeping the form widget independent of extensions.
+See [templates.md](templates.md) for Liquid syntax and supported namespaces.

package/docs/hooks.md

@@ -248,23 +248,91 @@ fetch-only for now.
 
 ```ts
 interface ExportHook {
+  getExportTypes?(args: {}, ctx): Promise<ExportTypeDefinition[]>
   suggestExportOptions?(args: ExportOptionsRequest, ctx): Promise<ExportOption[]>
   generateExport(args: ExportRequest, ctx): Promise<ExportResult>
 }
 // ExportOptionsRequest: {operation, qsos, compactFilenames?}
-// ExportOption: {exportType, format, label, filename?, icon?, color?, refType?, priority?, selectedByDefault?}
-// ExportRequest: {operation, qsos, exportType?, compactFilenames?}  — full QSON, one coarse call
+// ExportOption: {exportType, exportKey?, format, label, filename?, icon?, color?, refType?, priority?, selectedByDefault?}
+// ExportRequest: {operation, qsos, exportType?, exportKey?, compactFilenames?}  — full QSON, one coarse call
 // ExportResult:  {filename, mimeType, content}
 ```
 
 Two-step flow: the Exports Panel calls `suggestExportOptions` on every
 `export` hook to build its selectable list (a hook that omits it never
 appears in the panel), then calls `generateExport` — passing back the
-chosen option's `exportType` — only for the options the user selected. The
-core owns file I/O and save/share; the hook only produces content.
+chosen option's `exportType` and `exportKey` — only for the options the user
+selected. The core owns file I/O and save/share; the hook only produces content.
+
+`exportType` is the stable kind (for example `potaActivation-adif`); `exportKey`
+identifies an individual option within the hook (for example
+`pota-adif:US-1234`). Options sharing a type must have distinct keys. Omit
+`exportKey` for a single option of a type: selection and generation default
+it to `exportType`. Both values round-trip unchanged when an explicit key is
+provided; the core does not interpret them. Selection also includes the
+hook key and station callsign, keeping different hooks and stations independent.
+
 Exporters should compose per-QSO program fields from `adifFields` hooks (see
-below) rather than knowing about specific activities. Implemented by: `adif`
-(key `adif`, one option); Cabrillo will register here too.
+below) rather than knowing about specific activities. Implemented by the whole-log `adif` exporter, activity exports, and contest
+ADIF/Cabrillo exporters.
+
+**Registering types and settings.** `getExportTypes` runs without an operation,
+so Settings can list types even before the operator has a matching log:
+
+```ts
+async getExportTypes() {
+  return [{
+    exportType: 'potaActivation-adif',
+    activationType: 'potaActivation',
+    format: 'adif',
+    label: 'POTA',
+    defaults: { includePrivateData: false, includeLookupData: true },
+  }]
+}
+```
+
+Prefer `<activationType>-<format>` to an extension-key namespace. Two
+extensions offering that type share one settings entry. The highest-priority
+registration supplies its definition; other exporters using it must honor
+that contract. Distinct sponsor requirements can use a distinct type. The
+SDK's `exportTypeDefinition(activationType, format, label, defaults?)` builds
+the conventional definition; the activity and hunting helpers register their
+own types. An exporter without `getExportTypes` still works, but does not
+appear in the export settings list.
+
+`ExportSettings` contains `includePrivateData`, `includeLookupData`,
+`customTemplates`, `filenameTemplate`, `compactFilenameTemplate`,
+`titleTemplate`, `adifNotesTemplate`, `adifCommentTemplate`, and
+`adifQslMessageTemplate`. All are optional. Defaults resolve from the SDK,
+then global preferences, then the type's declared defaults.
+`GlobalExportSettings` adds `referenceFilenameTemplate`,
+`referenceCompactFilenameTemplate`, `referenceTitleTemplate` and the matching
+`other…` fields. A type with `templateCategory: 'reference'` uses the reference
+set; other types use the other set. The activity export helper registers
+reference types automatically. ADIF field templates remain common to both sets.
+Saved common filename/title defaults remain fallbacks for categories without
+an explicit setting. Per-type data
+choices override those; per-type template overrides apply only when
+`customTemplates` is on. Empty templates intentionally suppress text. Turning
+custom templates off preserves the operator's edits for later. Non-ADIF
+formats expose only the filename templates and their custom-template switch.
+
+Type definitions may supply `templateSample: {operation, log}` for representative
+editor examples. Each format supplies its own filename extension in the sample.
+
+An option can supply `qsoCount` when its hook further filters the contacts
+(for example, a hunter export). Otherwise the host derives the count from
+activity and station scope. Filename and title templates use this count.
+
+Options can carry `templateData: {ref, refName, activity, modifier, ...}`,
+which populates the `log` namespace. The app renders filenames and titles
+before showing the option, and passes the same `exportSettings`, `exportData`
+and `exportTitle` to generation. It also passes the resolved
+`includePrivateData` and `includeLookupData` for ADIF. Forward those fields
+when delegating through `adifForExport`, or a program's preferences will not
+reach the ADIF writer. Settings apply globally and per type, never per operation.
+The whole-log ADIF defaults to including private data, but its type setting
+can override that default.
 
 **How a row looks.** `refType` names the activity the export covers — the
 core slices the file's QSOs by it, and the panel takes the row's icon and

package/docs/settings.md

@@ -372,17 +372,18 @@ Aliases are for names an operator would plausibly *reach for* — not a thesauru
 Every alias is one more thing that can collide with another setting's real name,
 and a collision costs a disambiguation prompt on a query that used to be exact.
 
-## Common Settings and environment gating
+## Common Preferences and environment gating
 
-The app has one settings screen, **Settings**: a collapsible section per
-declared group and panel, led by **Common Settings**, a short list of the
+The app has one settings screen, **Settings**, whose **Application
+Preferences** panel has a collapsible section per declared group and panel,
+led by **Common Preferences**, a short list of the
 handful of settings most users ever touch. Which fields land on Common
-Settings —
+Preferences —
 and which platforms show a field at all — is declared per-element, not
 maintained as a separate list somewhere else in the app. Any field, link, or
 action (core-declared or extension-declared, Tier 1 or Tier 2 alike) can set:
 
-- **`common: true`** — also show this element in the Common Settings
+- **`common: true`** — also show this element in the Common Preferences
   section, on top of its own group's. Off by default. Not the same thing as
   `FormFieldOption.common`/`uncommon` above — that's a `multiselect`
   option's own disclosure tier (upfront vs. behind "Show more"), a
@@ -395,7 +396,7 @@ action (core-declared or extension-declared, Tier 1 or Tier 2 alike) can set:
 - **`environment: 'ios,android'`** (or `'-web'`, or an array either way) —
   restrict which platform(s) show this element at all. This is a platform
   gate, not a common-vs-everything one: an excluded field disappears from every
-  settings surface on that platform, not just Common Settings. Every
+  settings surface on that platform, not just Common Preferences. Every
   token unprefixed is a whitelist (show ONLY there); every token
   `-`-prefixed is a blacklist (show everywhere EXCEPT there); mixing the two
   forms in one attribute is invalid and treated as if `environment` were

package/docs/templates.md

@@ -19,7 +19,7 @@ const text = renderTemplate("{{ op.station }} — {{ op.qsoCount }} QSOs", templ
 
 A template is DATA. Liquid parses and interprets; Handlebars compiles
 through `new Function`. These templates are written by operators, copied
-between operators, and will eventually be editable in settings, so the one
+between operators, and are editable in settings, so the one
 that cannot become code is the one to have. Liquid also has comparisons
 (`{% if op.qsoCount > 100 %}`) and loops built in, where Handlebars needs a
 registered helper for `>` and Mustache cannot compare at all.
@@ -42,15 +42,15 @@ the namespaces are deliberately polo's. The syntax around them does not:
 |---|---|---|---|---|
 | `app` | ✓ | — | ✓ | ✓ |
 | `now` | ✓ | ✓ | ✓ | ✓ |
-| `op` | ✓ | dates only | ✓ | ✓ |
+| `op` | ✓ | ✓ | ✓ | ✓ |
 | `qso` | when the placement's triggers ask for it | — | ✓ | the draft contact, as far as it is typed |
 | `config` | ✓ | — | — | — |
 | `log` | — | ✓ | ✓ | — |
 
 A namespace a surface has nothing for is **absent**, not blank — which is
-what makes `{% if qso %}` an honest question. Filenames get only the date
-half of `op` because a filename is built from parts rather than from an
-operation (`exportNames.ts`).
+what makes `{% if qso %}` an honest question. Registered exports get the operation plus the selected file’s `log` values.
+The low-level `exportFilename(parts)` helper still supplies only dates and
+filename parts.
 
 ### `app`
 `app.name` — the platform-appropriate name ("Ham2K Logger" on desktop,
@@ -191,16 +191,16 @@ will jump rather than count. Show HH:MM.
 | what | where | editable |
 |---|---|---|
 | Panel documents | `custom-text`'s content and tab name | by the operator, in the panel's config form |
-| Export filenames | `sdk/src/exportNames.ts` `NAME_TEMPLATES` | not yet |
-| ADIF NOTES / COMMENT / QSLMSG | `core/adif`'s `TEXT_FIELD_TEMPLATES` | not yet |
+| Export filenames and titles | Registered export types and `sdk/src/exportSettings.ts` | Settings → Exports, globally and per type |
+| ADIF NOTES / COMMENT / QSLMSG | Export type settings, consumed by `core/adif` | Settings → Exports; empty templates suppress a field |
 | CW messages | Radio settings `cwMessage1..8`, keyed on F1-F8 through the radio (docs/design/cat.md § CW keying) — rendered by the `template` hook (hooks.md) | by the operator, in the Station dialog's Messages… dialog |
 
-COMMENT and QSLMSG are empty, so nothing is written for them. app-polo
-defaults COMMENT to the QSO's notes and QSLMSG to the operation's
-references; both wait here until there is a settings screen to edit them in,
-since a default nobody can see is one nobody can turn off, and these fields
-travel to a program's servers.
+NOTES and COMMENT default to QSO notes and are withheld when private data
+is off. QSLMSG defaults to empty for program exports, and to the operation’s
+references for the whole-log ADIF. Custom QSL messages may use contact values.
+Templates receive no withheld private or lookup values. File titles obey the
+private-data choice; filename templates are labels for the operator’s files.
 
-Whatever fills them must respect the private/public split: `notes` is the
-operator's own words and belongs only in a field the export withholds when
-private data is off. NOTES is such a field. COMMENT and QSLMSG are not.
+The `textTemplate` form field provides sample previews and an insertable
+reference; see [forms.md](forms.md). Invalid Liquid reports an error rather
+than silently replacing the operator’s template with a default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",