@camox/api-contract 0.78.0 → 0.79.0

package/dist/threads.js

@@ -153,6 +153,7 @@ const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"addMemory",
 	"applyFindingFix",
 	"changeMemory",
+	"changeVoice",
 	"copyFromPastWork",
 	"createBlock",
 	"createCollectionRecord",
@@ -165,6 +166,7 @@ const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"editCollectionRecord",
 	"moveBlock",
 	"removeLocale",
+	"retranslateLocale",
 	"retranslateLocalization",
 	"setPageLayout",
 	"setPageSeo",

package/dist/voice.d.ts

@@ -0,0 +1,191 @@
+//#region src/voice.d.ts
+/**
+ * The Voice Axes, each with its steps in order and each step's one-line definition. The Voice is
+ * a limit, not a target, and each axis's `limit` says how: under a `ceiling`, copy may sit at any
+ * step below the chosen one, never above; in a `band`, within one step of it either way.
+ */
+export declare const VOICE_AXES: readonly [{
+  readonly key: "formality";
+  readonly limit: "band";
+  readonly name: "Formality";
+  readonly about: "register, grammar, vocabulary";
+  readonly steps: readonly [{
+    readonly key: "ceremonial";
+    readonly name: "Ceremonial";
+    readonly definition: "elevated, ritual register; no contractions; set phrases and honorifics.";
+  }, {
+    readonly key: "formal";
+    readonly name: "Formal";
+    readonly definition: "correct and impersonal; no contractions or slang; complete sentences.";
+  }, {
+    readonly key: "neutral";
+    readonly name: "Neutral";
+    readonly definition: "standard written register; contractions allowed; no slang.";
+  }, {
+    readonly key: "conversational";
+    readonly name: "Conversational";
+    readonly definition: "as spoken to a customer; contractions, short sentences, questions to the reader.";
+  }, {
+    readonly key: "colloquial";
+    readonly name: "Colloquial";
+    readonly definition: "as spoken among friends; slang, fragments, loose grammar.";
+  }];
+}, {
+  readonly key: "humor";
+  readonly limit: "ceiling";
+  readonly name: "Humor";
+  readonly about: null;
+  readonly steps: readonly [{
+    readonly key: "grave";
+    readonly name: "Grave";
+    readonly definition: "solemn and weighty; treats its subject with gravity, beyond having no jokes.";
+  }, {
+    readonly key: "earnest";
+    readonly name: "Earnest";
+    readonly definition: "sincere and straightforward; no jokes.";
+  }, {
+    readonly key: "light";
+    readonly name: "Light";
+    readonly definition: "warm, with an occasional light touch; no set-up jokes.";
+  }, {
+    readonly key: "witty";
+    readonly name: "Witty";
+    readonly definition: "jokes, irony or playful exaggeration recur.";
+  }, {
+    readonly key: "irreverent";
+    readonly name: "Irreverent";
+    readonly definition: "mocks conventions, the industry or itself; jokes over sincerity.";
+  }];
+}, {
+  readonly key: "claimStrength";
+  readonly limit: "ceiling";
+  readonly name: "Claim strength";
+  readonly about: "how strongly copy praises and promises, backed or not; calls to action count only when they push urgency";
+  readonly steps: readonly [{
+    readonly key: "understated";
+    readonly name: "Understated";
+    readonly definition: "states facts only; no praise words; qualifies claims.";
+  }, {
+    readonly key: "measured";
+    readonly name: "Measured";
+    readonly definition: "modest claims; praise words are rare.";
+  }, {
+    readonly key: "confident";
+    readonly name: "Confident";
+    readonly definition: "states benefits plainly; few praise words, no superlatives.";
+  }, {
+    readonly key: "assertive";
+    readonly name: "Assertive";
+    readonly definition: "praise words throughout; strong claims and comparisons.";
+  }, {
+    readonly key: "bold";
+    readonly name: "Bold";
+    readonly definition: "superlatives, sweeping promises, urgency, exclamations.";
+  }];
+}, {
+  readonly key: "expertise";
+  readonly limit: "ceiling";
+  readonly name: "Expertise";
+  readonly about: "what the reader is assumed to know";
+  readonly steps: readonly [{
+    readonly key: "plain";
+    readonly name: "Plain";
+    readonly definition: "everyday words only; no terms of the trade.";
+  }, {
+    readonly key: "accessible";
+    readonly name: "Accessible";
+    readonly definition: "terms of the trade only when explained.";
+  }, {
+    readonly key: "informed";
+    readonly name: "Informed";
+    readonly definition: "common terms of the trade, unexplained.";
+  }, {
+    readonly key: "technical";
+    readonly name: "Technical";
+    readonly definition: "precise terms, specifications and figures for practitioners.";
+  }, {
+    readonly key: "specialist";
+    readonly name: "Specialist";
+    readonly definition: "dense jargon and references only experts follow.";
+  }];
+}, {
+  readonly key: "density";
+  readonly limit: "ceiling";
+  readonly name: "Density";
+  readonly about: "words per idea, not page length";
+  readonly steps: readonly [{
+    readonly key: "telegraphic";
+    readonly name: "Telegraphic";
+    readonly definition: "fragments and lists; articles and transitions dropped where possible.";
+  }, {
+    readonly key: "concise";
+    readonly name: "Concise";
+    readonly definition: "one idea per short sentence; nothing restated.";
+  }, {
+    readonly key: "balanced";
+    readonly name: "Balanced";
+    readonly definition: "each idea gets the sentence it needs, with transitions.";
+  }, {
+    readonly key: "descriptive";
+    readonly name: "Descriptive";
+    readonly definition: "ideas get detail, qualification and imagery.";
+  }, {
+    readonly key: "expansive";
+    readonly name: "Expansive";
+    readonly definition: "ideas developed at length, with asides and restatement.";
+  }];
+}, {
+  readonly key: "distance";
+  readonly limit: "band";
+  readonly name: "Distance";
+  readonly about: "who speaks, how close";
+  readonly steps: readonly [{
+    readonly key: "institutional";
+    readonly name: "Institutional";
+    readonly definition: "the organization speaks of itself by name, in the third person, and doesn't address the reader.";
+  }, {
+    readonly key: "collective";
+    readonly name: "Collective";
+    readonly definition: '"we" speak about readers in general.';
+  }, {
+    readonly key: "direct";
+    readonly name: "Direct";
+    readonly definition: '"we" speak to "you".';
+  }, {
+    readonly key: "personal";
+    readonly name: "Personal";
+    readonly definition: '"we" speak to "you" one to one, sharing opinions and feelings.';
+  }, {
+    readonly key: "solo";
+    readonly name: "Solo";
+    readonly definition: 'one person speaks as "I".';
+  }];
+}];
+/** One Voice Axis, with its steps in order. */
+export type VoiceAxis = (typeof VOICE_AXES)[number];
+export type VoiceAxisKey = VoiceAxis["key"];
+/** A step of the axis `A`. */
+export type VoiceStep<A extends VoiceAxisKey = VoiceAxisKey> = Extract<VoiceAxis, {
+  key: A;
+}>["steps"][number];
+/** The key of a step of the axis `A`. */
+export type VoiceStepKey<A extends VoiceAxisKey = VoiceAxisKey> = VoiceStep<A>["key"];
+/** A Voice: the chosen step on each axis. */
+export type Voice = { [A in VoiceAxisKey]: VoiceStepKey<A>; };
+/** The Voice a new project starts with: no hype, no wordiness, no forced jokes. */
+export declare const DEFAULT_VOICE: Voice;
+/** The axis with this key. */
+export declare const voiceAxis: <A extends VoiceAxisKey>(key: A) => Extract<VoiceAxis, {
+  key: A;
+}>;
+/** Whether `key` names a step of the axis `axis`. */
+export declare const isVoiceStep: <A extends VoiceAxisKey>(axis: A, key: string) => key is VoiceStepKey<A>;
+/** The step with this key on the axis `axis`. */
+export declare const voiceStep: <A extends VoiceAxisKey>(axis: A, key: VoiceStepKey<A>) => VoiceStep<A>;
+/** An axis a draft moves: from Live's step to the draft's. */
+export type VoiceChange = { [A in VoiceAxisKey]: {
+  axis: A;
+  before: VoiceStepKey<A>;
+  after: VoiceStepKey<A>;
+}; }[VoiceAxisKey];
+//#endregion

package/dist/voice.js

@@ -0,0 +1,228 @@
+//#region src/voice.ts
+/**
+* The Voice Axes, each with its steps in order and each step's one-line definition. The Voice is
+* a limit, not a target, and each axis's `limit` says how: under a `ceiling`, copy may sit at any
+* step below the chosen one, never above; in a `band`, within one step of it either way.
+*/
+const VOICE_AXES = [
+	{
+		key: "formality",
+		limit: "band",
+		name: "Formality",
+		about: "register, grammar, vocabulary",
+		steps: [
+			{
+				key: "ceremonial",
+				name: "Ceremonial",
+				definition: "elevated, ritual register; no contractions; set phrases and honorifics."
+			},
+			{
+				key: "formal",
+				name: "Formal",
+				definition: "correct and impersonal; no contractions or slang; complete sentences."
+			},
+			{
+				key: "neutral",
+				name: "Neutral",
+				definition: "standard written register; contractions allowed; no slang."
+			},
+			{
+				key: "conversational",
+				name: "Conversational",
+				definition: "as spoken to a customer; contractions, short sentences, questions to the reader."
+			},
+			{
+				key: "colloquial",
+				name: "Colloquial",
+				definition: "as spoken among friends; slang, fragments, loose grammar."
+			}
+		]
+	},
+	{
+		key: "humor",
+		limit: "ceiling",
+		name: "Humor",
+		about: null,
+		steps: [
+			{
+				key: "grave",
+				name: "Grave",
+				definition: "solemn and weighty; treats its subject with gravity, beyond having no jokes."
+			},
+			{
+				key: "earnest",
+				name: "Earnest",
+				definition: "sincere and straightforward; no jokes."
+			},
+			{
+				key: "light",
+				name: "Light",
+				definition: "warm, with an occasional light touch; no set-up jokes."
+			},
+			{
+				key: "witty",
+				name: "Witty",
+				definition: "jokes, irony or playful exaggeration recur."
+			},
+			{
+				key: "irreverent",
+				name: "Irreverent",
+				definition: "mocks conventions, the industry or itself; jokes over sincerity."
+			}
+		]
+	},
+	{
+		key: "claimStrength",
+		limit: "ceiling",
+		name: "Claim strength",
+		about: "how strongly copy praises and promises, backed or not; calls to action count only when they push urgency",
+		steps: [
+			{
+				key: "understated",
+				name: "Understated",
+				definition: "states facts only; no praise words; qualifies claims."
+			},
+			{
+				key: "measured",
+				name: "Measured",
+				definition: "modest claims; praise words are rare."
+			},
+			{
+				key: "confident",
+				name: "Confident",
+				definition: "states benefits plainly; few praise words, no superlatives."
+			},
+			{
+				key: "assertive",
+				name: "Assertive",
+				definition: "praise words throughout; strong claims and comparisons."
+			},
+			{
+				key: "bold",
+				name: "Bold",
+				definition: "superlatives, sweeping promises, urgency, exclamations."
+			}
+		]
+	},
+	{
+		key: "expertise",
+		limit: "ceiling",
+		name: "Expertise",
+		about: "what the reader is assumed to know",
+		steps: [
+			{
+				key: "plain",
+				name: "Plain",
+				definition: "everyday words only; no terms of the trade."
+			},
+			{
+				key: "accessible",
+				name: "Accessible",
+				definition: "terms of the trade only when explained."
+			},
+			{
+				key: "informed",
+				name: "Informed",
+				definition: "common terms of the trade, unexplained."
+			},
+			{
+				key: "technical",
+				name: "Technical",
+				definition: "precise terms, specifications and figures for practitioners."
+			},
+			{
+				key: "specialist",
+				name: "Specialist",
+				definition: "dense jargon and references only experts follow."
+			}
+		]
+	},
+	{
+		key: "density",
+		limit: "ceiling",
+		name: "Density",
+		about: "words per idea, not page length",
+		steps: [
+			{
+				key: "telegraphic",
+				name: "Telegraphic",
+				definition: "fragments and lists; articles and transitions dropped where possible."
+			},
+			{
+				key: "concise",
+				name: "Concise",
+				definition: "one idea per short sentence; nothing restated."
+			},
+			{
+				key: "balanced",
+				name: "Balanced",
+				definition: "each idea gets the sentence it needs, with transitions."
+			},
+			{
+				key: "descriptive",
+				name: "Descriptive",
+				definition: "ideas get detail, qualification and imagery."
+			},
+			{
+				key: "expansive",
+				name: "Expansive",
+				definition: "ideas developed at length, with asides and restatement."
+			}
+		]
+	},
+	{
+		key: "distance",
+		limit: "band",
+		name: "Distance",
+		about: "who speaks, how close",
+		steps: [
+			{
+				key: "institutional",
+				name: "Institutional",
+				definition: "the organization speaks of itself by name, in the third person, and doesn't address the reader."
+			},
+			{
+				key: "collective",
+				name: "Collective",
+				definition: "\"we\" speak about readers in general."
+			},
+			{
+				key: "direct",
+				name: "Direct",
+				definition: "\"we\" speak to \"you\"."
+			},
+			{
+				key: "personal",
+				name: "Personal",
+				definition: "\"we\" speak to \"you\" one to one, sharing opinions and feelings."
+			},
+			{
+				key: "solo",
+				name: "Solo",
+				definition: "one person speaks as \"I\"."
+			}
+		]
+	}
+];
+/** The Voice a new project starts with: no hype, no wordiness, no forced jokes. */
+const DEFAULT_VOICE = {
+	formality: "conversational",
+	humor: "earnest",
+	claimStrength: "confident",
+	expertise: "accessible",
+	density: "concise",
+	distance: "direct"
+};
+/** The axis with this key. */
+const voiceAxis = (key) => VOICE_AXES.find((axis) => axis.key === key);
+/** Whether `key` names a step of the axis `axis`. */
+const isVoiceStep = (axis, key) => {
+	return voiceAxis(axis).steps.some((step) => step.key === key);
+};
+/** The step with this key on the axis `axis`. */
+const voiceStep = (axis, key) => {
+	return voiceAxis(axis).steps.find((step) => step.key === key);
+};
+
+//#endregion
+export { DEFAULT_VOICE, VOICE_AXES, isVoiceStep, voiceAxis, voiceStep };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "license": "UNLICENSED",
   "files": [
     "src",
@@ -59,6 +59,10 @@
     "./claim-links": {
       "types": "./dist/claim-links.d.ts",
       "default": "./dist/claim-links.js"
+    },
+    "./voice": {
+      "types": "./dist/voice.d.ts",
+      "default": "./dist/voice.js"
     }
   },
   "dependencies": {

package/src/drafts.ts

@@ -335,12 +335,14 @@ const SPECIALISTS_WRITES: Record<keyof Router["specialists"], boolean> = {
   dismissFinding: false,
 };
 
-// Memory changes through drafts, like content (ADR 0049).
+// Memory, the Voice included, changes through drafts, like content (ADR 0049, ADR 0051).
 const MEMORY_WRITES: Record<keyof Router["memories"], boolean> = {
   list: false,
   add: true,
   change: true,
   delete: true,
+  voice: false,
+  saveVoice: true,
 };
 
 // `definitions` is absent: its sync is a release, never a studio content write.

package/src/query-keys.ts

@@ -52,9 +52,10 @@ export const queryKeys = {
   layouts: {
     all: ["camox", "layouts"],
   },
-  // A scope's memory (ADR 0049).
+  // A scope's memory (ADR 0049), and its Voice (ADR 0051).
   memories: {
     list: ["camox", "memories", "list"],
+    voice: ["camox", "memories", "voice"],
   },
   drafts: {
     all: ["camox", "drafts"],

package/src/threads.ts

@@ -188,6 +188,7 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   "addMemory",
   "applyFindingFix",
   "changeMemory",
+  "changeVoice",
   "copyFromPastWork",
   "createBlock",
   "createCollectionRecord",
@@ -200,6 +201,7 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   "editCollectionRecord",
   "moveBlock",
   "removeLocale",
+  "retranslateLocale",
   "retranslateLocalization",
   "setPageLayout",
   "setPageSeo",