agentic-ads-engine 0.0.0-stage → 0.2.0

package/src/index.js

@@ -0,0 +1,64 @@
+import { listRules, getRule } from './qa/index.js';
+export { listRules, getRule, checklistFor, costRatchet } from './qa/index.js';
+import { listFormats, getFormat, planFormat } from './formats/index.js';
+export { listFormats, getFormat, planFormat };
+import { templates } from './templates/index.js';
+import { hooks, selectFor, listHooks, getHook, pickHooks, emotions } from './hooks/index.js';
+import { lint } from './policy/index.js';
+import { templateProvider, guardCost } from './providers/index.js';
+export { listHooks, getHook, pickHooks, templates, hooks, selectFor, lint, templateProvider, guardCost };
+export { readScores, writeScores } from './hooks/index.js';
+const string = { type: 'string' };
+const hookFilters = { format: string, emotion: { type: 'string', enum: emotions }, housing: { type: 'boolean' } };
+const fields = {
+  list_hooks: hookFilters, pick_hooks: hookFilters, get_hook: { id: string },
+  list_qa_rules: {}, get_qa_rule: { id: string },
+  list_formats: { costClass: { type: 'string', enum: ['free', 'cheap', 'mid', 'expensive'] }, risk: { type: 'string', enum: ['low', 'medium', 'high'] } },
+  get_format: { id: string },
+  plan_format: { format: string, site: string, goal: string, dryRun: { type: 'boolean' } },
+  'list-templates': {}, 'list-hooks': {},
+  lint: { copy: string, category: { enum: ['housing', 'none'], type: 'string' } },
+  plan: { site: string, goal: string, template: string, ratio: { enum: ['4:5', '9:16'], type: 'string' }, copy: string, category: { enum: ['housing', 'none'], type: 'string' }, apply: { type: 'boolean' }, dryRun: { type: 'boolean' } },
+};
+export const tools = Object.entries(fields).map(([name, properties]) => ({
+  name, description: ({ list_hooks: 'List hooks with optional filters.', pick_hooks: 'Pick matching hooks in stable score order.', get_hook: 'Get one hook.', list_qa_rules: 'List owner feedback QA rules.', get_qa_rule: 'Get an owner feedback QA rule.', list_formats: 'List video formats with optional cost and risk filters.', get_format: 'Get a video format descriptor.', plan_format: 'Plan video stages offline. Apply is unavailable.', 'list-templates': 'List starter template descriptors.', 'list-hooks': 'List hook patterns and risks.', lint: 'Check ad copy; findings always require review.', plan: 'Preview a zero-cost plan. Apply is unavailable.' })[name],
+  inputSchema: { type: 'object', properties, additionalProperties: false, ...({ pick_hooks: ['format'], get_hook: ['id'], lint: ['copy'], get_qa_rule: ['id'], get_format: ['id'], plan_format: ['format', 'site'] }[name] ? { required: { pick_hooks: ['format'], get_hook: ['id'], lint: ['copy'], get_qa_rule: ['id'], get_format: ['id'], plan_format: ['format', 'site'] }[name] } : {}) },
+}));
+/** Shared CLI/MCP dispatch. Unknown inputs fail before any action. */
+export function execute(action, args = {}) {
+  if (!Object.hasOwn(fields, action)) throw new Error('Unknown action');
+  if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('Invalid arguments');
+  if (args.apply === true && ['plan', 'plan_format'].includes(action)) throw new Error('Apply is unavailable in this offline slice');
+  for (const key of tools.find(t => t.name === action).inputSchema.required ?? []) if (args[key] === undefined) throw new Error('Missing required argument: ' + key);
+  for (const [key, value] of Object.entries(args)) {
+    const field = fields[action][key];
+    if (!Object.hasOwn(fields[action], key) || typeof value !== field.type || (field.enum && !field.enum.includes(value))) throw new Error('Invalid argument');
+    if (typeof value === 'string' && value.length > 20000) throw new Error('Argument too long');
+  }
+  if (action === 'list_hooks') return listHooks(args);
+  if (action === 'pick_hooks') return pickHooks(args);
+  if (action === 'get_hook') return getHook(args.id);
+  if (action === 'list_qa_rules') return listRules();
+  if (action === 'get_qa_rule') return getRule(args.id);
+  if (action === 'list_formats') return listFormats(args);
+  if (action === 'get_format') return getFormat(args.id);
+  if (action === 'plan_format') return planFormat(args);
+  if (action === 'list-templates') return structuredClone(templates);
+  if (action === 'list-hooks') return structuredClone(hooks);
+  if (action === 'lint') return lint(args.copy, args);
+  if (args.apply === true) throw new Error('Apply is unavailable in this offline slice');
+  if (args.dryRun === false) throw new Error('Use dry-run; apply is unavailable');
+  const descriptor = templates.find(t => t.id === (args.template ?? 'door-open-teaser'));
+  if (!descriptor) throw new Error('Unknown template');
+  const site = args.site ?? 'demo';
+  const hook = selectFor({ id: site }, args.goal ?? 'discovery');
+  if (!hook) throw new Error('No low-risk hook matches this goal');
+  const copy = args.copy ?? hook.pattern.replace('{{subject}}', 'available listings');
+  const policy = lint(copy, args);
+  const estimate = templateProvider.estimate();
+  return { dryRun: true, applied: false, site, template: descriptor.id, ratio: args.ratio ?? '4:5', hook,
+    copy, policy, estimate, costGuard: guardCost({ costMinor: 0, adSpentMinor: 0, monthSpentMinor: 0, perAdMinor: 0, perMonthMinor: 0 }),
+    requiredSlots: descriptor.slots.map(s => s.name),
+    warnings: ['No image is rendered or campaign launched.', 'Supply verified slots and brand tokens to the provider.', ...descriptor.risk === 'high' ? ['High-risk template requires additional review.'] : []],
+  };
+}

package/src/policy/index.js

@@ -0,0 +1,112 @@
+// This lint is a warning tool, not legal advice. It misses cases.
+// Every result still needs a person to review it.
+// Normalize invisible separators and common Latin lookalikes before all checks.
+const lookalikes = { ı: 'i', а: 'a', е: 'e', о: 'o', р: 'p', с: 'c', х: 'x', у: 'y', і: 'i', ј: 'j', ѕ: 's', к: 'k', м: 'm', т: 't', в: 'b', н: 'h', ι: 'i', α: 'a', ε: 'e', ο: 'o', ρ: 'p', χ: 'x', υ: 'y', κ: 'k', τ: 't', ν: 'v' };
+function normalize(copy) {
+  return copy.normalize('NFKC').toLowerCase().normalize('NFD').replace(/\p{M}/gu, '')
+    .replace(/[\u00ad\u034f\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/g, '')
+    .replace(/[ıаеорсхуіјѕкмтвнαεορχυκτνι]/g, c => lookalikes[c]);
+}
+function hasContact(text) {
+  // Each token/run is scanned once. Do not retry an unbounded suffix at every character.
+  if (text.split(/\s+/).some(token => /^[^@]+@[^@.]+\.[^@]+$/.test(token))) return true;
+  const withoutDates = text
+    .replace(/\b(?:parcel(?:[ -]+id)?|assessor[ -]+parcel)[ :#-]*[\d-]+\b/g, ' ')
+    .replace(/\b(?:\d{4}[-/.]\d{1,2}[-/.]\d{1,2}|\d{1,2}[-/.]\d{1,2}[-/.]\d{4})\b/g, ' ');
+  for (const match of withoutDates.matchAll(/[+\d][\d\s().-]*/g)) {
+    const digits = match[0].replace(/\D/g, '').length;
+    if (digits >= 10) return true;
+  }
+  return false;
+}
+function hasPlaceholder(text) {
+  const start = text.indexOf('{{');
+  return start !== -1 && text.indexOf('}}', start + 2) !== -1;
+}
+function hasHousing(text) {
+  const subject = text.replace(/\b(?:apartment design games?|auction software|art listings?|lease accounting software|flat tires?|flat rates?|home page|home runs?|house music)\b/g, '');
+  return /\b(?:homes?|housing|houses?|condos?|condominiums?|apartments?|leases?|leasing|renting|rented|townhouses?|duplex(?:es)?|landlords?|tenants?|bedrooms?|studios?|\d+br|flats?|real estate|foreclosures?|rent(?:al|als)?|propert(?:y|ies)|mortgages?|auctions?|listings?)\b/.test(subject);
+}
+// Bounded connectors keep cues attached to people, without scanning arbitrary prose.
+const gap = '[\\s-]+';
+const spaced = pattern => pattern.replaceAll(' ', gap);
+const people = spaced('(?:(?:tenants?|residents?|applicants?|people|persons?|households?|roommates?|family|families|professionals?|with|or|and|pets|grad|job|on|are|is) ){0,4}');
+const modifier = spaced('(?:(?:a|an) )?(?:(?:young|single|mature|professional|traditional|able bodied) )?');
+const cueBefore = spaced('(?:only|no|not|not for|wanted|prefer|prefers|seeking|seeks|preferred|ideal for|great for|perfect for|must be|must have|must speak|exclude|excluding|not suitable for)');
+const cueAfter = spaced('(?:only|preferred|wanted|required|excluded|exclusive|need not apply|not welcome|not accepted|not allowed|not permitted|prohibited|banned)');
+function preference(subject, welcomeSignals = false) {
+  const group = spaced(subject);
+  // 'X welcome' is inclusive for income, family, age, marital status and disability. For religion,
+  // race, origin and sex it signals a preference, so those rules pass welcomeSignals = true.
+  const after = welcomeSignals ? '(?:' + cueAfter + '|welcome)' : cueAfter;
+  return new RegExp('\\b(?:' + cueBefore + gap + people + modifier + '(?:' + group + ')|(?:' + group + ')' + gap + people + after + ')\\b');
+}
+// Keep age numbers bounded, including common written ages.
+const ageNumber = '(?:\\d{1,2}|(?:twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety)(?:[ -](?:one|two|three|four|five|six|seven|eight|nine))?|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen)';
+const ageSpan = ageNumber + '\\s*(?:(?:to|thru|through|[-\\u2013])\\s*' + ageNumber + '|\\+|plus)(?!\\w)';
+const ageRange = new RegExp('\\b(?:age[sd]?(?:[ -]+range)?[\\s-]*' + ageSpan + '|must[ -]+be[ -]+(?:under|over|younger than|older than)[ -]+' + ageNumber + '\\b)');
+const childAmenity = new RegExp('\\b(?:kids|children)[ -]+age[sd]?[\\s-]*' + ageSpan + '[ -]+(?:play[ -]+area|playground)\\b', 'g');
+const ageRestriction = {
+  // Remove only the amenity phrase. Other restrictions in the copy still apply.
+  test: text => ageRange.test(text.replace(childAmenity, ' ')),
+};
+const postalTerm = '(?:(?:zip|postal)(?:[\\s-]*codes?)?|postcodes?)';
+const postalRestriction = new RegExp('\\b(?:' + postalTerm + '[\\s-]+only|(?:only|just)[\\s-]+(?:in[\\s-]+)?(?:these[\\s-]+|the[\\s-]+)?' + postalTerm + '|' + postalTerm + '[\\s-]*(?:targeting|restricted)|' + postalTerm + '[ -]+(?:\\d{5}(?:-\\d{4})?|[a-z]{1,2}\\d[a-z\\d]?[ -]+\\d[a-z]{2})[ -]+(?:residents?[ -]+)?only)\\b');
+const housingRules = [
+  ['targeting_age', preference('young(?: professionals?| adults?)?|seniors?|retirees?|millennials?|students?|mature|elderly|teens?|teenagers?|toddlers?|babies|infants?'), 'Remove age or student restrictions and preferences.'],
+  ['targeting_familial_status', preference('children|child|kids|kiddos|family|families|parents?|mothers?|fathers?|pregnant'), 'Remove family-status restrictions and preferences.'],
+  ['targeting_familial_status', preference('adults?|empty nesters'), 'Remove family-status restrictions and preferences.'],
+  ['targeting_marital_status', preference('singles?|bachelors?|couples?|married|unmarried|divorced'), 'Remove marital-status restrictions and preferences.'],
+  ['targeting_religion', preference('christians?|muslims?|jewish|jews?|hindus?|buddhists?|catholics?|protestants?|believers|religious', true), 'Remove religious targeting or preferences.'],
+  ['targeting_income', preference('section (?:8|eight)|vouchers?|hud|housing assistance|public assistance|income source|job income|welfare|ssi|ssdi|disability income|social security'), 'Remove source-of-income restrictions or preferences.'],
+  ['targeting_sex', preference('men|women|males?|females?|boys?|girls?|gentlemen|ladies|sex|gender|gay|straight', true), 'Remove sex or gender restrictions and preferences.'],
+  ['targeting_origin', preference('americans?|canadians?|chinese|indians?|mexicans?|british|french|arabs?|hispanics?|latinos?|latinas?|africans?|asians?|(?:us )?citizens?|native speakers?|english(?: speakers?)?|immigrants?|foreigners?|national origin|ethnicity|race|whites?|blacks?|minorities', true), 'Remove race or national-origin restrictions and preferences.'],
+  ['targeting_disability', preference('disabled|handicapped|deaf|blind|disability|disabilities|mentally ill|wheelchairs?(?: users?)?|service animals?|able bodied|non disabled|wheelchair accessible'), 'Remove disability restrictions and preferences.'],
+  // Indirect occupancy language needs review even without an explicit restriction.
+  ['targeting_familial_status', /\b(?:traditional[\s-]+family[\s-]+values[\s-]+neighbou?rhood|adult[\s-]+community|only[\s-]+one[\s-]+child)\b/, 'Review possible family-status or occupancy preferences.', 'warning'],
+  ['targeting_religion', /\b(?:christian|muslim|jewish|hindu|buddhist|catholic|protestant)[\s-]+home\b/, 'Review possible religious occupancy preferences.', 'warning'],
+  ['targeting_disability', /\bmust[\s-]+be[\s-]+able[\s-]+to[\s-]+climb[\s-]+stairs\b/, 'Review possible disability restrictions in stair-access requirements.', 'warning'],
+  // These phrases describe eligibility or preferred occupants, rather than a bare class word.
+  ['targeting_age', /\b(?:(?:over|under|older than|younger than)[ -]+\d{1,3}[ -]+(?:community|residents?|tenants?|only)|(?:\d{1,3}|fifty[ -]five)[ -]*(?:\+|plus\b|(?:and|or)[ -]+(?:over|older|up)\b|years?[ -]+(?:old|(?:and|or)[ -]+(?:over|older))\b)|senior living|retirement community)\b/, 'Remove age eligibility language.'],
+  ['targeting_age', /\b\d{1,3}\+(?=[ -]+(?:community|residents?|tenants?|only)\b)/, 'Remove age eligibility language.'],
+  ['targeting_familial_status', /\b(?:family[ -]friendly|child[ -]free)\b/, 'Remove family-status preferences.'],
+  ['targeting_religion', /\b(?:christian|muslim|jewish|hindu|buddhist|catholic|protestant)[ -]+(?:neighbou?rhood|community|building)(?!\s+(?:cent(?:er|re)|hall|school|hospital|museum|library|church|temple|mosque|synagogue))\b/, 'Remove religious neighborhood preferences.'],
+  ['targeting_sex', /\b(?:gay|straight)[ -]friendly\b/, 'Remove sex or gender preferences.'],
+  ['targeting_area', /\b(?:zip|postal)[ -]+(?:code[ -]+)?\d{1,10}[ -]+only\b|\b(?:target|targeting|exclude|excluding)\s+(?:residents?\s+)?(?:in\s+)?(?:(?:this|that|the|these|specific|selected)\s+)?(?:areas?|neighbou?rhoods?|districts?)\b|\b(?:locals?|area residents?)\s+only\b/, 'Remove postal or area targeting language.'],
+  ['targeting_age', ageRestriction, 'Remove age ranges or limits.'],
+  ['targeting_area', postalRestriction, 'Remove ZIP-code targeting.'],
+];
+/** Conservative copy checks, not platform approval or factual verification.
+ * @param {string} copy
+ * @param {{category?:string}} options
+ */
+export function lint(copy, options = {}) {
+  if (typeof copy !== 'string' || copy.length > 20000) throw new Error('Copy must be a string of at most 20000 characters');
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new Error('Invalid lint options');
+  const { category = 'housing' } = options;
+  if (!['housing', 'none'].includes(category)) throw new Error('Unsupported category');
+  const text = normalize(copy);
+  // Preserve punctuation for contact and date checks. Normalize it only for targeting.
+  const targetingText = text.replace(/\bu\.s\.(?=[\s_.-])/g, 'us').replace(/[_.]/g, ' ');
+  const findings = [];
+  const add = (code, message, severity = 'error') => findings.push({ code, severity, message });
+  if (!text.trim()) add('empty', 'Supply ad copy.');
+  const housing = category === 'housing' || hasHousing(text);
+  if (category !== 'housing' && housing) add('housing_category', 'Declare the housing Special Ad Category.');
+  const rules = [
+    ...(housing ? housingRules : []),
+    ['deceptive', /\b(guarantee\w*|risk[ -]?free|zero risk|no risk|double your money|instant profit)\b/, 'Remove promises of certain outcomes.'],
+    ['superlative', /\b(best(?![ -]street\b)|top(?![ -](?:floor\b|\d+\b|rated\b|notch\b|tier\b))|largest|fastest|cheapest|unbeatable|number one)\b|#\s*1\b/, 'Remove banned superlatives.'],
+    ['below_market', /\b(?:below|under|off|less[ -]+than|cheaper[ -]+than|discount(?:ed)?[ -]+(?:from|against|to))[ -]+(?:(?:the|current|local|fair|estimated|average|prevailing|open)[ -]+){0,5}(?:market|appraisal|appraised[ -]+value|comps)\b|\bmarket\s+(?:value|rates?|prices?)\s+(?:minus|less|discount)/, 'A below-market claim needs independent evidence and review.'],
+    ['urgency', /\b(only today|ending soon|limited time|act now|last chance|only \d+ left)\b/, 'Verify scarcity and timing before use.'],
+    ['news', /\b(breaking(?![ -]down\b)|news alert)\b/, 'News framing needs review and a clear ad disclosure.'],
+    ['staging', /\b(before.{0,12}after|virtually staged|virtual staging|ai.staged)\b/, 'Verify the source images and staging disclosure.'],
+  ];
+  for (const [code, pattern, message, severity] of rules) {
+    if (pattern.test(code.startsWith('targeting_') ? targetingText : text)) add(code, message, severity);
+  }
+  if (hasContact(text)) add('private_data', 'Remove contact data.');
+  if (hasPlaceholder(text)) add('placeholder', 'Replace unresolved slots before review.');
+  add('human_review', 'This lint is a warning tool, not legal advice. It misses cases. Every result needs a person to review facts, consent, disclosures, and platform rules.', 'warning');
+  return { status: findings.some(f => f.severity === 'error') ? 'blocked' : 'review', category, findings };
+}

package/src/providers/index.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { templates } from '../templates/index.js';
+/** @typedef {{capabilities:Function, estimate:Function, run:Function}} Provider */
+/** Pure cap check in integer minor units of one caller-selected currency.
+ * Existing spend must include reservations and uncertain charges.
+ */
+export function guardCost(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Invalid cost or cap');
+  const values = {};
+  for (const key of ['costMinor', 'adSpentMinor', 'monthSpentMinor', 'perAdMinor', 'perMonthMinor']) {
+    if (!Object.hasOwn(input, key)) throw new Error(`Invalid cost or cap: ${key} must be an own property`);
+    const value = input[key];
+    values[key] = value;
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error('Invalid cost or cap');
+  }
+  if ('apply' in input && !Object.hasOwn(input, 'apply')) throw new Error('Invalid cost or cap: apply must be an own property');
+  const { costMinor, adSpentMinor, monthSpentMinor, perAdMinor, perMonthMinor } = values;
+  const apply = input.apply;
+  const reasons = [];
+  if (costMinor > 0 && apply !== true) reasons.push('apply_required');
+  if (costMinor > perAdMinor - adSpentMinor) reasons.push('per_ad_cap');
+  if (costMinor > perMonthMinor - monthSpentMinor) reasons.push('monthly_cap');
+  return { ok: reasons.length === 0, reasons };
+}
+const escape = value => value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+/** HTML-to-image adapter stub. It emits deterministic HTML only, never a raster image. */
+export const templateProvider = {
+  id: 'html-template-stub',
+  capabilities: () => ({ formats: ['text/html'], aspectRatios: ['4:5', '9:16'], imageRendering: false }),
+  estimate: () => ({ costMinor: 0, currency: 'USD', confidence: 'exact' }),
+  run(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Invalid provider input');
+    const { template, ratio = '4:5', slots, brand = {} } = input;
+    const descriptor = templates.find(t => t.id === template);
+    if (!descriptor || !descriptor.aspectRatios.includes(ratio)) throw new Error('Invalid template or ratio');
+    if (!slots || typeof slots !== 'object' || Array.isArray(slots)) throw new Error('Invalid slots');
+    if (!brand || typeof brand !== 'object' || Array.isArray(brand)) throw new Error('Invalid brand');
+    if (Object.keys(slots).some(k => !descriptor.slots.some(s => s.name === k))) throw new Error('Unknown slot');
+    if (Object.keys(brand).some(k => !descriptor.brandTokens.includes(k))) throw new Error('Unknown brand token');
+    const colors = { primary: '#2455cc', background: '#ffffff', foreground: '#151515' };
+    for (const key of Object.keys(colors)) {
+      colors[key] = brand[key] ?? colors[key];
+      if (typeof colors[key] !== 'string' || !/^#[0-9a-f]{6}$/i.test(colors[key])) throw new Error('Invalid brand color');
+    }
+    const name = brand.name ?? 'Demo';
+    if (typeof name !== 'string' || !name.trim() || name.length > 80) throw new Error('Invalid brand name');
+    const body = descriptor.slots.map(slot => {
+      const value = Object.hasOwn(slots, slot.name) ? slots[slot.name] : undefined;
+      if (typeof value !== 'string' || !value.trim() || value.length > slot.maxChars) throw new Error('Invalid required slot');
+      return `<section data-slot="${slot.name}">${escape(value)}</section>`;
+    }).join('');
+    const width = 1080, height = ratio === '4:5' ? 1350 : 1920;
+    const html = `<!doctype html><html><head><meta charset="utf-8"><title>Ad preview</title><style>body{margin:0;width:${width}px;height:${height}px;box-sizing:border-box;padding:80px;background:${colors.background};color:${colors.foreground};font:48px sans-serif}header{color:${colors.primary}}section{margin:40px 0;overflow-wrap:anywhere}</style></head><body data-template="${descriptor.id}"><header>${escape(name)}</header>${body}</body></html>`;
+    return { html, mime: 'text/html', width, height, image: null, sha256: createHash('sha256').update(html).digest('hex'), costMinor: 0, warnings: ['Stub: HTML only; image rendering is unavailable.'] };
+  },
+};

package/src/qa/index.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+const rules = JSON.parse(readFileSync(new URL('./rules.json', import.meta.url), 'utf8'));
+export function listRules() { return structuredClone(rules); }
+export function getRule(id) {
+  const rule = rules.find(r => r.id === id);
+  if (!rule) throw new Error('Unknown QA rule: ' + String(id) + '. Use qa-rules to list available IDs.');
+  return structuredClone(rule);
+}
+/** Accept a format descriptor. Review status never implies that checks ran. */
+export function checklistFor(format) {
+  return format.feedbackRules.map(id => {
+    const { title, check } = getRule(id);
+    return { id, title, check, status: 'NOT CHECKED' };
+  });
+}
+export const costRatchet = "Set a hard cap before you spend. One writer per spend log.\nReuse faces, sets, stills, clips and voice ids from earlier videos first.\nPick one lip-sync model for a format and keep it. Do not repeat a bake-off.\nDo not make the same still twice. Do not pay for an unused line.\nWrite `COST_NOTES.md`. Show cost per stage and against the last video of the format.\nA video that costs more than the last one of its format needs a one-line reason.";

package/src/qa/rules.json

@@ -0,0 +1,28 @@
+[
+  {"id": "R1", "title": "Wild emotional hook in the first second.", "check": "Watch 0 to 1 s with sound off. Record what frame 0.0 s shows. It must be a strong emotion or an odd event. In a format with a person, R20 applies.", "origin": "Round 3 hook was \"not intriguing\".", "severity": "blocking", "applies": ["all"]},
+  {"id": "R2", "title": "Cause comes before effect on screen. Show the action, then the result, then who reacts. In a format with a person, the reaction face of R20 comes first. Then the order is action, result, reaction, all by 3 s.", "check": "Step through 0 to 3 s. No character appears without a reason. No object is already broken.", "origin": "Sitcom: door fell, people appeared at 0:02.", "severity": "blocking", "applies": ["story"]},
+  {"id": "R3", "title": "Change the camera angle, not only the zoom.", "check": "Look at the frames: the scene-cut filter cannot see a zoom. About one new angle or pose every 2.5 s. Cuts differ in height, pose or distance. A side change stays on one side of the 180-degree line (R21).", "origin": "\"Different left and right views, not slow zooms.\"", "severity": "blocking", "applies": ["character"]},
+  {"id": "R4", "title": "The same person must show different poses and angles.", "check": "Same face, outfit and hair across all shots. At least 3 poses.", "origin": "Marble lady needed jump cuts.", "severity": "blocking", "applies": ["character"]},
+  {"id": "R5", "title": "Show problem, agitation, then solution. Make the agitation hurt and be funny.", "check": "Mark the three beats on the timeline. Agitation has at least 3 quick cuts, one prop each.", "origin": "\"Highlight problem and solution agitation.\"", "severity": "blocking", "applies": ["story"]},
+  {"id": "R6", "title": "No dead gaps. No silent still over 0.3 s. Tail after the last sound under 0.3 s.", "check": "`freezedetect=n=-60dB:d=0.3` crossed with `silencedetect=n=-35dB:d=0.25`. A range in both is a dead gap.", "origin": "Round 4 had dead gaps.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R7", "title": "Speed up the picture, not the voice. Normal speech pace.", "check": "Words per second from whisper: 2 to 3. Average shot length: 1.5 to 2.2 s for a lo-fi story (the gate in `qa.md`), 1.2 to 1.5 s only for a fast punch edit. No shot over 2.5 s.", "origin": "\"Sound speed too much, pace better.\"", "severity": "blocking", "applies": ["all"]},
+  {"id": "R8", "title": "Voice, face and ethnicity must match.", "check": "A person listens to each voice with the face. Log the voice id per character.", "origin": "\"Ethnicity of source does not match.\"", "severity": "blocking", "applies": ["character"]},
+  {"id": "R9", "title": "A story the viewer can follow. It is personal and coherent, in the first person, as a dramatization. It makes no factual claim.", "check": "Read the captions alone. They tell one story in the first person.", "origin": "Meltdown: \"random words\".", "severity": "blocking", "applies": ["story"]},
+  {"id": "R10", "title": "Captions have spaces. At most 3 words. Time them to the audio.", "check": "Measure the pixel gap: at least 14 px of clear gap between words at 1080 px. Compare caption start with the whisper word start (under 0.15 s).", "origin": "Caption spacing and sync.", "severity": "blocking", "applies": ["captions"]},
+  {"id": "R11", "title": "Mouth movement matches speech. Mouths close in laugh breaks.", "check": "Manual spot check until measured: mouth movement starts within 100 to 200 ms of voice onset (see `ad-video-editing` qa.md section 6). Where a lip-landmark tool ran, give its correlation (0.4 or more) and the tool name. List each failing line.", "origin": "Sitcom v2 and v3.", "severity": "blocking", "applies": ["dialogue", "speech"]},
+  {"id": "R12", "title": "Never cut to a static image that makes no sense.", "check": "Check each cut. Every shot has motion or a reason to hold.", "origin": "Sitcom v2 feedback.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R13", "title": "Back-and-forth dialogue is wanted. Keep it and add more.", "check": "Count speaker changes. At least 4 in a sitcom.", "origin": "\"Love the dialogue.\"", "severity": "blocking", "applies": ["dialogue"]},
+  {"id": "R14", "title": "Sound is required. The ad also works muted.", "check": "Play with sound off. The story and the offer still read. Ship both files.", "origin": "Round 3 had no sound.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R15", "title": "Hold the object identity. A phone stays a phone.", "check": "Compare held objects in frames across the clip.", "origin": "Phone turned into a notepad.", "severity": "blocking", "applies": ["character"]},
+  {"id": "R16", "title": "Lo-fi organic look. No logo. No text except captions, the dramatization tag and one end card with the offer.", "check": "Look at the frames. No logo, no studio polish.", "origin": "Polished images were rejected.", "severity": "blocking", "applies": ["lo-fi"]},
+  {"id": "R17", "title": "Housing safety. \"dramatization\" label. No invented numbers. No real people. No children.", "check": "Run the policy lint on all text and captions.", "origin": "Housing special ad category.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R18", "title": "Cost goes down each time. Report cost per video by stage.", "check": "Compare with the last video of the same format. Explain any rise.", "origin": "Goal: cut cost 50 to 75 percent.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R19", "title": "Do not show an event the video model cannot render. Show damage another way.", "check": "Render one clip first. Look at 3 frames of the event. No duplicate objects (two doors), no melting. If it fails, change the beat (cracking wall, falling plaster).", "origin": "\"No crash, two doors, AI artifact.\"", "severity": "blocking", "applies": ["all"]},
+  {"id": "R20", "title": "In a format with a person, the first frame is that person's reaction face. The cause follows in the next shot or two (see R2). This replaces the 0.0 s check in R1 for those formats.", "check": "Frame 0.0 s: a face, eyes and mouth readable, emotion matches the hook. The cause is on screen by 3 s.", "origin": "\"Shocked face in the first frame.\"", "severity": "blocking", "applies": ["character"]},
+  {"id": "R21", "title": "Keep screen direction. Each person stays on the same side of the frame in every shot. Change the angle on one side of the 180-degree line. Do not cross it.", "check": "List left/right per shot for each person. No swap, including cutaways.", "origin": "Street interview: host moved from right to left.", "severity": "blocking", "applies": ["dialogue"]},
+  {"id": "R22", "title": "A conversation looks like one: eyelines, head turns, small hand gestures, a slow push-in on the punchline. Do the push-in in the edit as a crop. Ask the model for small gestures only.", "check": "Per talking shot: where does the person look? Count eyeline-matched reverse shots (at least 1). Note the crop push-in. OWNER CHECK for how natural it looks.", "origin": "\"Talk as if to someone, more hand movement, zoom in on the guy.\"", "severity": "blocking", "applies": ["dialogue"]},
+  {"id": "R23", "title": "Captions never look jumbled.", "check": "Compile `swiftc -O ocr.swift` (macOS Vision, `VNRecognizeTextRequest`, accurate, language correction off). Run it on one frame per caption from the final render. Retry once on an `e5rt` crash. Character error rate (edit distance divided by expected length, upper case, spaces collapsed) 0.10 or less. Do not run `swift ocr.swift` (it hangs).", "origin": "\"Some letters get jumbled.\"", "severity": "blocking", "applies": ["captions"]},
+  {"id": "R24", "title": "Show the tool of the format. A street interview shows the microphone in the host's hand. Name the mic in the motion prompt and include it in the R15 frame comparison.", "check": "Frame check: mic visible in every host shot, same shape in each.", "origin": "Interview had no visible mic.", "severity": "blocking", "applies": ["interview"]},
+  {"id": "R25", "title": "A horror-comic variant needs a scare beat: something moves behind a door, a sting, a reaction. Then it resolves as a joke.", "check": "Mark the beat on the timeline. A sting starts within 0.2 s of the beat, then a reaction shot. OWNER CHECK for how scary it feels.", "origin": "\"Feel a little bit scared.\"", "severity": "blocking", "applies": ["horror"]},
+  {"id": "R26", "title": "A personal story has a clear hook: the loss, the place, the trust that broke, the surprise. The offer is on the end card. The narrator never says the product worked. See R9 and R17.", "check": "Caption read: one sentence per beat, in that order. No line claims a result.", "origin": "\"I spent all my savings on this house ... a slick agent gave me a lien ... someone lives there.\"", "severity": "blocking", "applies": ["story"]}
+]

package/src/templates/index.js

@@ -0,0 +1,26 @@
+/** @typedef {{name:string, required:boolean, maxChars:number, source:string}} Slot */
+/** @typedef {{id:string, version:number, name:string, aspectRatios:string[], slots:Slot[], beats:string[], risk:string}} Template */
+const slot = (name, source = 'source') => ({ name, source, required: true, maxChars: 240 });
+/** @type {Template[]} */
+export const templates = [
+  ['door-open-teaser', 'Door-open teaser', ['detail'], ['Door reveal', 'Show the actual condition', 'Invite a closer look'], 'low'],
+  ['ugc-first-person', 'UGC first-person', ['experience', 'disclosure'], ['First-person introduction', 'Verified experience', 'Ad disclosure and invitation'], 'medium'],
+  ['honest-before-after', 'Honest before/after', ['before', 'after', 'disclosure'], ['Same view before', 'Same view after', 'Explain actual or virtual changes'], 'medium'],
+  ['breaking-news-frame', 'Breaking-news frame', ['fact', 'source', 'disclosure'], ['Brand update banner', 'Dated and sourced fact', 'Clearly identify this as an ad'], 'high'],
+  ['help-urgency', 'Help/urgency', ['problem', 'help', 'timing'], ['Name the task', 'Offer practical help', 'Use only verified timing'], 'medium'],
+].map(([id, name, extra, beats, risk]) => ({
+  id, name, version: 1, aspectRatios: ['4:5', '9:16'], risk, beats,
+  slots: [slot('headline', 'hook'), ...extra.map(x => slot(x)), slot('cta', 'cta')],
+  brandTokens: ['name', 'primary', 'background', 'foreground'],
+  renderer: 'template', costClass: 'free', policy: { textExact: true, imageMayContainText: false },
+}));
+
+// Freeze every nested descriptor so callers cannot change rendering limits or risk.
+function deepFreeze(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+deepFreeze(templates);