brand-intent 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-intent",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "An open file format specification for making brand intent machine-readable.",
   "author": "Christophe Stoll <christophe@stoll.studio>",
   "license": "MIT",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "release": "./scripts/release.sh",
-    "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.test.ts && tsx tests/colorSystem.test.ts && tsx tests/icons.test.ts && tsx tests/realBrands.test.ts"
+    "test": "tsx tests/brandParser.test.ts && tsx tests/identityParser.test.ts && tsx tests/colorSystem.test.ts && tsx tests/icons.test.ts && tsx tests/purposeParser.test.ts && tsx tests/realBrands.test.ts"
   },
   "devDependencies": {
     "tsx": "^4.19.0"

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';
@@ -351,7 +372,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 = '';
@@ -398,6 +419,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];
@@ -767,6 +791,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 +873,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) {
@@ -1473,6 +1533,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/index.ts

@@ -23,7 +23,7 @@ export {
   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). */
@@ -96,7 +100,8 @@ export interface ParsedPurposeSlot {
     autofitMin: number;
     autofitMax: number;
     textAlign: 'left' | 'center' | 'right' | 'justify';
-    hyphenate: boolean;
+    /** true = hyphenate freely (body text); 'fit' = only when a word doesn't fit at autofit-min. */
+    hyphenate: boolean | 'fit';
   }>;
 }
 
@@ -131,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;
@@ -314,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;
     }
 
@@ -419,6 +434,7 @@ export function parsePurposeFile(content: string, fileName: string): ParsedPurpo
         if (prop === 'uppercase: false') { currentSlot.typographyOverrides.uppercase = false; continue; }
         if (prop === 'hyphenate' || prop === 'hyphenate: true') { currentSlot.typographyOverrides.hyphenate = true; continue; }
         if (prop === 'hyphenate: false') { currentSlot.typographyOverrides.hyphenate = false; continue; }
+        if (prop === 'hyphenate: fit') { currentSlot.typographyOverrides.hyphenate = 'fit'; continue; }
         if (prop === 'autofit: none' || prop === 'autofit:none') {
           currentSlot.typographyOverrides.autofitMin = -1;
           currentSlot.typographyOverrides.autofitMax = -1;
@@ -650,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/vscode-extension/syntaxes/brand.tmLanguage.json

@@ -31,6 +31,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" },
@@ -366,7 +367,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 +411,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 +456,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": {
@@ -165,7 +173,15 @@
           }
         },
         {
-          "match": "^\\s{4,}(italic|uppercase|hyphenate)(?:(:)\\s+(true|false))?\\s*$",
+          "match": "^\\s{4,}(italic|uppercase)(?:(:)\\s+(true|false))?\\s*$",
+          "captures": {
+            "1": { "name": "support.type.property-name.brand-intent-purpose" },
+            "2": { "name": "punctuation.separator.brand-intent-purpose" },
+            "3": { "name": "constant.language.brand-intent-purpose" }
+          }
+        },
+        {
+          "match": "^\\s{4,}(hyphenate)(?:(:)\\s+(true|false|fit))?\\s*$",
           "captures": {
             "1": { "name": "support.type.property-name.brand-intent-purpose" },
             "2": { "name": "punctuation.separator.brand-intent-purpose" },
@@ -234,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" }
           }