brand-intent 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",

package/parser/brandParser.ts

@@ -112,6 +112,27 @@ export interface ParsedBrand {
   icons?: ParsedIconDef[];
   /** List counter component (`counter` block). */
   counter?: ParsedCounterDef;
+  /** Photo framing modules (`framing NAME` blocks), in declaration order. Absent → no camera guides. */
+  framings?: ParsedFramingDef[];
+  /** Camera defaults (`camera` block). Absent → rear camera, no grid. */
+  camera?: ParsedCameraDef;
+}
+
+export interface ParsedCameraDef {
+  /** Which camera opens first. */
+  facing: 'front' | 'rear';
+  /** Viewfinder grid as rows × columns of cells. Absent → no grid. */
+  grid?: { rows: number; cols: number };
+}
+
+export interface ParsedFramingDef {
+  id: string;
+  /** Display name. Defaults to the id. */
+  label: string;
+  /** Horizon position as % of image height, measured from the top. null → no horizon (close-ups). */
+  horizon: number | null;
+  /** The photographic task, one line. */
+  description?: string;
 }
 
 export type CounterFormat = '1' | '01' | '1.' | '(1)' | 'i';
@@ -229,6 +250,14 @@ const VALID_STRATEGIES = new Set<PaletteStrategy>(['monochrome', 'duotone', 'tri
 const VALID_ADHERENCES = new Set<Adherence>(['strict', 'on-brand', 'flexible']);
 const TONE_CLASSES = new Set<ToneClass>(['light', 'mid', 'dark']);
 const FAMILY_ROLES = new Set<FamilyRole>(['core', 'accent', 'contrast']);
+
+const DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function isMonthDay(value: string): boolean {
+  const m = value.match(/^(\d{2})-(\d{2})$/);
+  if (!m) return false;
+  const month = Number(m[1]), day = Number(m[2]);
+  return month >= 1 && month <= 12 && day >= 1 && day <= DAYS_IN_MONTH[month - 1];
+}
 const FAMILY_ORDERS = new Set<FamilyOrder>(['cycle', 'sequence']);
 const FAMILY_BORROWS = new Set<FamilyBorrow>(['previous', 'next', 'both', 'none']);
 const PAIR_KEYS = ['ground', 'figure', 'text'] as const;
@@ -351,7 +380,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     tokensSource: 'figma',
   };
 
-  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta' | 'icons' | 'counter';
+  type ActiveBlock = 'none' | 'brand-colors' | 'state-colors' | 'color-bounds' | 'color-adherence' | 'color-rules' | 'color-families' | 'theme' | 'spacing' | 'divider' | 'typography' | 'font' | 'logo' | 'photo' | 'video' | 'illustration' | 'label' | 'cta' | 'icons' | 'counter' | 'framing' | 'camera';
   let activeBlock: ActiveBlock = 'none';
   let currentThemeName = '';
   let currentDividerName = '';
@@ -374,7 +403,7 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   const adherenceOverridesRaw: Record<string, string> = {};
   const colorRulesRaw: Record<string, string> = {};
   let colorRulesDeclared = false;
-  type RawFamily = { name: string; line: number; colors: Array<{ role: string; value: string; line: number }>; pairs: Array<{ ground: string; figure: string; line: number }> };
+  type RawFamily = { name: string; line: number; from?: string; colors: Array<{ role: string; value: string; line: number }>; pairs: Array<{ ground: string; figure: string; line: number }> };
   const familiesProps: Record<string, string> = {};
   const familiesRaw: RawFamily[] = [];
   let familiesDeclared = false;
@@ -398,6 +427,9 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
   let iconsDeclared = false;
   const counterRaw: Record<string, { value: string; line: number }> = {};
   let counterDeclared = false;
+  const cameraRaw: Record<string, { value: string; line: number }> = {};
+  let cameraDeclared = false;
+  const framingsRaw: Array<{ id: string; line: number; props: Record<string, { value: string; line: number }> }> = [];
 
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i];
@@ -629,8 +661,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         const colonIdx = trimmed.indexOf(':');
         const key = colonIdx !== -1 ? trimmed.slice(0, colonIdx).trim() : trimmed;
+        if (key === 'from' && colonIdx !== -1) {
+          const value = trimmed.slice(colonIdx + 1).trim();
+          if (currentFamily.from !== undefined) throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}" declares from: twice`);
+          if (!isMonthDay(value)) throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}" from: must be "MM-DD" (e.g. 12-01), got "${value}"`);
+          inPairs = false;
+          currentFamily.from = value;
+          continue;
+        }
         if (colonIdx === -1 || !FAMILY_ROLES.has(key as FamilyRole)) {
-          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected core / accent / contrast / pairs, got "${trimmed}"`);
+          throw new Error(`${fileName}:${lineNum}: family "${currentFamily.name}": expected from / core / accent / contrast / pairs, got "${trimmed}"`);
         }
         inPairs = false;
         currentFamily.colors.push({ role: key, value: trimmed.slice(colonIdx + 1).trim(), line: lineNum });
@@ -767,6 +807,24 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         counterRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
         continue;
       }
+      if (activeBlock === 'camera') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        const commentIdx = trimmed.search(/\s+#/);
+        const entry = commentIdx !== -1 ? trimmed.slice(0, commentIdx) : trimmed;
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1) throw new Error(`${fileName}:${lineNum}: camera property must be "KEY: VALUE", got "${trimmed}"`);
+        cameraRaw[entry.slice(0, colonIdx).trim()] = { value: entry.slice(colonIdx + 1).trim(), line: lineNum };
+        continue;
+      }
+      if (activeBlock === 'framing') {
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('#')) continue;
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) throw new Error(`${fileName}:${lineNum}: framing property must be "KEY: VALUE", got "${trimmed}"`);
+        framingsRaw[framingsRaw.length - 1].props[trimmed.slice(0, colonIdx).trim()] = { value: trimmed.slice(colonIdx + 1).trim(), line: lineNum };
+        continue;
+      }
       // Indented line with no active block — ignore
       continue;
     }
@@ -831,6 +889,24 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
       continue;
     }
 
+    // camera — camera defaults (facing, viewfinder grid)
+    if (raw.trim() === 'camera') {
+      if (cameraDeclared) throw new Error(`${fileName}:${lineNum}: duplicate camera block`);
+      cameraDeclared = true;
+      activeBlock = 'camera';
+      continue;
+    }
+
+    // framing <id> — photo framing module (horizon position)
+    const framingMatch = raw.match(/^framing\s+(\S+)\s*$/);
+    if (framingMatch) {
+      const id = framingMatch[1];
+      if (framingsRaw.some(f => f.id === id)) throw new Error(`${fileName}:${lineNum}: duplicate framing "${id}"`);
+      framingsRaw.push({ id, line: lineNum, props: {} });
+      activeBlock = 'framing';
+      continue;
+    }
+
     // theme ThemeName — starts a theme block
     const themeMatch = raw.match(/^theme\s+(\S+)/);
     if (themeMatch) {
@@ -1090,7 +1166,16 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
         }
         brandColors[c.key] = c.hex;
       }
-      families.push({ name: raw.name, colors, pairs: [] });
+      families.push({ name: raw.name, ...(raw.from ? { from: raw.from } : {}), colors, pairs: [] });
+    }
+    const dated = familiesRaw.filter(f => f.from !== undefined);
+    if (dated.length > 0 && dated.length < familiesRaw.length) {
+      const missing = familiesRaw.filter(f => f.from === undefined).map(f => f.name).join(', ');
+      throw new Error(`${fileName}: color-families: from: must be declared on every family or on none (missing: ${missing})`);
+    }
+    for (const f of dated) {
+      const twin = dated.find(o => o !== f && o.from === f.from);
+      if (twin) throw new Error(`${fileName}:${f.line}: families "${twin.name}" and "${f.name}" share from: ${f.from}`);
     }
     colorFamilies = { order, borrow, distance, shared, families };
     if (borrow !== 'none' && reachCoversAll(families.length, { order, borrow, distance })) {
@@ -1473,6 +1558,52 @@ export function parseBrandFile(content: string, fileName: string): ParsedBrand {
     result.counter = counter;
   }
 
+  // Finalise camera defaults
+  if (cameraDeclared) {
+    const known = new Set(['facing', 'grid']);
+    for (const [key, { line }] of Object.entries(cameraRaw)) {
+      if (!known.has(key)) throw new Error(`${fileName}:${line}: unknown camera property "${key}"`);
+    }
+    const facing = cameraRaw['facing']?.value ?? 'rear';
+    if (facing !== 'front' && facing !== 'rear') {
+      throw new Error(`${fileName}:${cameraRaw['facing'].line}: camera facing must be front | rear, got "${facing}"`);
+    }
+    const camera: ParsedCameraDef = { facing };
+    const g = cameraRaw['grid'];
+    if (g) {
+      // "3" → 3 × 3, "3 4" → 3 rows × 4 columns
+      const nums = g.value.split(/\s+/).map(Number);
+      const [rows, cols = rows] = nums;
+      if (nums.length > 2 || ![rows, cols].every(n => Number.isInteger(n) && n >= 2 && n <= 12)) {
+        throw new Error(`${fileName}:${g.line}: camera grid must be "N" or "ROWS COLS" (2–12), got "${g.value}"`);
+      }
+      camera.grid = { rows, cols };
+    }
+    result.camera = camera;
+  }
+
+  // Finalise framing modules
+  if (framingsRaw.length > 0) {
+    const known = new Set(['label', 'horizon', 'description']);
+    result.framings = framingsRaw.map(({ id, line, props }) => {
+      for (const [key, { line: l }] of Object.entries(props)) {
+        if (!known.has(key)) throw new Error(`${fileName}:${l}: unknown framing property "${key}"`);
+      }
+      const h = props['horizon'];
+      if (!h) throw new Error(`${fileName}:${line}: framing "${id}" needs "horizon: N%" or "horizon: none"`);
+      let horizon: number | null = null;
+      if (h.value !== 'none') {
+        const m = h.value.match(/^(\d+(?:\.\d+)?)%$/);
+        const n = m ? parseFloat(m[1]) : NaN;
+        if (!(n > 0 && n < 100)) throw new Error(`${fileName}:${h.line}: framing horizon must be a percentage between 0% and 100% or "none", got "${h.value}"`);
+        horizon = n;
+      }
+      const def: ParsedFramingDef = { id, label: props['label']?.value || id, horizon };
+      if (props['description']?.value) def.description = props['description'].value;
+      return def;
+    });
+  }
+
   // Validate required fields
   const required: (keyof ParsedBrand)[] = ['id', 'name', 'language', 'locale'];
   for (const field of required) {

package/parser/colorSystem.ts

@@ -193,6 +193,23 @@ export function colorOrigin(
   return null;
 }
 
+/**
+ * Family in season on `date`: the one with the latest `from:` on or before that
+ * month/day, wrapping to the year's last start before the first one. Uses the
+ * date's local calendar day. -1 when the families declare no dates.
+ */
+export function familyIndexForDate(families: Pick<ColorFamily, 'from'>[], date: Date): number {
+  if (families.length === 0 || families.some(f => !f.from)) return -1;
+  const today = `${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  let best = -1;
+  let latest = -1;
+  families.forEach((f, i) => {
+    if (f.from! <= today && (best === -1 || f.from! > families[best].from!)) best = i;
+    if (latest === -1 || f.from! > families[latest].from!) latest = i;
+  });
+  return best !== -1 ? best : latest;
+}
+
 /** Name of the family that declares `hex` (first match), for error messages. */
 export function owningFamily(hex: string, families: ColorFamily[]): string | undefined {
   return families.find(f => f.colors.some(c => c.hex === hex))?.name;

package/parser/index.ts

@@ -20,10 +20,11 @@ export {
   familyTextCandidates,
   checkFamilyPair,
   enumerateFamilyPairs,
+  familyIndexForDate,
   DEFAULT_COLOR_RULES,
 } from './colorSystem';
 export type { ReachConfig } from './colorSystem';
-export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape } from './brandParser';
+export type { ParsedBrand, ParsedFontDef, ParsedTypographyDef, ParsedDividerDef, BrandColorPrintSpec, ParsedAssetDef, ParsedBadgeStyle, LogoAlign, ParsedCounterDef, CounterFormat, CounterShape, ParsedFramingDef, ParsedCameraDef } from './brandParser';
 
 export { parseIconRef, parseIconSource, resolveIconRef, parseListItem, phosphorName, PHOSPHOR_WEIGHTS } from './icons';
 export type { IconRef, IconSource, ParsedIconDef, ResolvedIcon, PhosphorWeight } from './icons';

package/parser/purposeParser.ts

@@ -38,6 +38,10 @@ export interface ParsedPurpose {
   defaultVideo?: string;
   /** When false, hides Take Photo / Upload buttons for this purpose. Default: true. */
   camera?: boolean;
+  /** `camera: front | rear` — overrides the brand's camera facing for this purpose. */
+  cameraFacing?: 'front' | 'rear';
+  /** `framing: <id>` — the brand framing module photos for this purpose are shot in. */
+  framing?: string;
   /** When false, photo/video analysis skips this purpose (no AI text generation). Default: true. */
   analyze?: boolean;
   /** Default icon for the icon slot. Resolves in the brand set first, then Phosphor (see resolveIconRef). */
@@ -132,6 +136,8 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
   let defaultPhoto: string | undefined;
   let defaultVideo: string | undefined;
   let camera: boolean | undefined;
+  let cameraFacing: 'front' | 'rear' | undefined;
+  let framing: string | undefined;
   let analyze: boolean | undefined;
   let defaultIcon: IconRef | undefined;
   let bgPrompt: string | undefined;
@@ -315,7 +321,15 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
 
     // Camera control
     if (line.startsWith('camera:')) {
-      camera = line.slice(7).trim() !== 'false';
+      const value = line.slice(7).trim();
+      camera = value !== 'false';
+      if (value === 'front' || value === 'rear') cameraFacing = value;
+      continue;
+    }
+
+    // Framing module: one of the brand's `framing NAME` blocks
+    if (line.startsWith('framing:')) {
+      framing = line.slice(8).trim() || undefined;
       continue;
     }
 
@@ -652,5 +666,5 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
     context = contextLines.join('\n').trim();
   }
 
-  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, analyze, defaultIcon, bgPrompt };
+  return { id, name, description, preferredCompositions: compositions, slots, density, palette, scope, context, voice, defaultLogo, defaultPhoto, defaultVideo, camera, cameraFacing, framing, analyze, defaultIcon, bgPrompt };
 }

package/parser/types.ts

@@ -156,6 +156,8 @@ export interface FamilyPair extends PairCheck {
 
 export interface ColorFamily {
   name: string;
+  /** Start date `MM-DD` (`from:`). Declared on every family or on none. */
+  from?: string;
   colors: FamilyColor[];
   pairs: FamilyPair[];
 }

package/vscode-extension/syntaxes/brand.tmLanguage.json

@@ -15,6 +15,7 @@
     { "include": "#color-rules-entry" },
     { "include": "#color-families-property" },
     { "include": "#family-header" },
+    { "include": "#family-from" },
     { "include": "#family-role" },
     { "include": "#family-pairs-keyword" },
     { "include": "#color-mode-enum" },
@@ -31,6 +32,7 @@
     { "include": "#icons-counter-header" },
     { "include": "#icon-entry" },
     { "include": "#counter-value" },
+    { "include": "#framing-horizon" },
     { "include": "#theme-header" },
     { "include": "#brand-color-entry" },
     { "include": "#brand-color-print-sub" },
@@ -142,6 +144,15 @@
         "5": { "name": "string.unquoted.brand-intent-brand" }
       }
     },
+    "family-from": {
+      "comment": "Family start date: from: MM-DD",
+      "match": "^(\\s{4,})(from)(:\\s*)(\\d{2}-\\d{2})\\s*$",
+      "captures": {
+        "2": { "name": "support.type.property-name.brand-intent-brand" },
+        "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
+        "4": { "name": "constant.numeric.brand-intent-brand" }
+      }
+    },
     "family-pairs-keyword": {
       "match": "^(\\s{4,})(pairs)\\s*$",
       "captures": {
@@ -366,7 +377,7 @@
       }
     },
     "asset-header": {
-      "match": "^(logo|photo|video|illustration)\\s+(\\S+)",
+      "match": "^(logo|photo|video|illustration|framing)\\s+(\\S+)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" },
         "2": { "name": "entity.name.type.brand-intent-brand" }
@@ -410,6 +421,16 @@
         "11": { "name": "comment.line.number-sign.brand-intent-brand" }
       }
     },
+    "framing-horizon": {
+      "comment": "framing block horizon: N% | none",
+      "match": "^(\\s{2,})(horizon)(:\\s*)(\\d+(?:\\.\\d+)?%|none)\\s*(#.*)?$",
+      "captures": {
+        "2": { "name": "support.type.property-name.brand-intent-brand" },
+        "3": { "name": "punctuation.separator.key-value.brand-intent-brand" },
+        "4": { "name": "constant.numeric.brand-intent-brand" },
+        "5": { "name": "comment.line.number-sign.brand-intent-brand" }
+      }
+    },
     "counter-value": {
       "comment": "counter block properties (typography: is covered by typography-value)",
       "match": "^(\\s{2,})(format|shape|size|padding)(:\\s*)(\\S+)\\s*(#.*)?$",
@@ -445,7 +466,7 @@
     },
     "keyword-partial": {
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
-      "match": "^(id:|name:|language:|locale:|domain:|app-icon:|favicon:|og-image:|tokens:|figma-file-key:|figma-collection:|tokens-file:|spacing:|label:|cta:|color-mode:|color-strategy:|color-adherence:|brand-colors|state-colors|color-bounds|color-rules|color-families|theme|divider|font|typography|logo|photo|video|illustration|icons|counter)(?=\\s|$)",
+      "match": "^(id:|name:|language:|locale:|domain:|app-icon:|favicon:|og-image:|tokens:|figma-file-key:|figma-collection:|tokens-file:|spacing:|label:|cta:|color-mode:|color-strategy:|color-adherence:|brand-colors|state-colors|color-bounds|color-rules|color-families|theme|divider|font|typography|logo|photo|video|illustration|icons|counter|framing)(?=\\s|$)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-brand" }
       }

package/vscode-extension/syntaxes/purpose.tmLanguage.json

@@ -14,6 +14,7 @@
     { "include": "#palette-header" },
     { "include": "#asset-field" },
     { "include": "#camera-field" },
+    { "include": "#framing-field" },
     { "include": "#analyze-field" },
     { "include": "#bg-prompt-field" },
     { "include": "#context-header" },
@@ -114,12 +115,19 @@
       }
     },
     "camera-field": {
-      "match": "^(camera:)\\s+(true|false)",
+      "match": "^(camera:)\\s+(true|false|front|rear)",
       "captures": {
         "1": { "name": "keyword.control.brand-intent-purpose" },
         "2": { "name": "constant.language.brand-intent-purpose" }
       }
     },
+    "framing-field": {
+      "match": "^(framing:)\\s+([\\w-]+)",
+      "captures": {
+        "1": { "name": "keyword.control.brand-intent-purpose" },
+        "2": { "name": "entity.name.type.brand-intent-purpose" }
+      }
+    },
     "analyze-field": {
       "match": "^(analyze:)\\s+(true|false)",
       "captures": {
@@ -242,7 +250,7 @@
       "comment": "Fallback: color the keyword token on incomplete lines (while typing)",
       "patterns": [
         {
-          "match": "^(id:|name:|compositions:|density:|defaultIcon:|scope|voice|palette:|logo:|photo:|video:|camera:|analyze:|bg-prompt:|context|slot)(?=\\s|$)",
+          "match": "^(id:|name:|compositions:|density:|defaultIcon:|scope|voice|palette:|logo:|photo:|video:|camera:|framing:|analyze:|bg-prompt:|context|slot)(?=\\s|$)",
           "captures": {
             "1": { "name": "keyword.control.brand-intent-purpose" }
           }