AutoLens Pipeline Explainer

export interface FigmaScanElementItem {
  nodeId: string; name: string;
  bbox: {x: number; y: number; width: number; height: number};
  class: string; //export-png | text-layer | separate-animated | separate-interactive
                 //| reuse-template-logo | use-bundled-hint | skip-* | container
  exportable: boolean;
  anchorHint: {left: number; right: number; bottom: number; top: number};
  action: string;
  text?: string; fontFamily?: string; fontSize?: number; textColor?: string;
  renderOrder?: number; stretchMode?: number;
}
export interface FigmaScanFrame {
  nodeId: string; name: string; page?: string;
  lensMode?: 'selfie' | 'world' | 'common';
  bbox: {width: number; height: number};
  elements: FigmaScanElementItem[];
  recommendations: string[]; nextSteps: string[];
}
export interface FigmaScan {
  fileKey: string; frames: FigmaScanFrame[];
  devNotes: {page: string; text: string}[];
  detectedMode?: 'common' | 'selfie' | 'world';
  flow?: FigmaProtoFlow;
}

src/lib/figma/scanTypes.ts:3-19,21-30,43-50 — tool wraps as {ok, scan, errors} at scanFigma.ts:202; class union at figmaApiImporter.ts:411

{ "ok": true, "scan": {
  "fileKey": "EXAMPLE_FILE_KEY", "detectedMode": "selfie",
  "frames": [ { "nodeId": "146:308", "name": "Fan Type 1", "bbox": {"width":334,"height":732},
    "elements": [
      {"nodeId":"146:311","name":"Type of Fan","class":"export-png","exportable":true,
       "action":"Bake to PNG → ImageLayer","bbox":{"x":76,"y":334,"width":182,"height":44},
       "anchorHint":{"left":-0.442,"right":0.4129,"bottom":-0.09,"top":0.03}},
      {"nodeId":"146:314","name":"Catchphrase","class":"text-layer","exportable":false,
       "action":"TEXT node → native Text","text":"You, my friend, are a","fontFamily":"Inter","fontSize":20,
       "anchorHint":{"left":-0.76,"right":0.76,"bottom":0.10,"top":0.18}},
      {"nodeId":"146:2","name":"Logo","class":"reuse-template-logo","exportable":false,
       "action":"Reuse template Logo SO (do not export)"},
      {"nodeId":"146:320","name":"Sparkle 1","class":"separate-animated","exportable":true,
       "action":"Separate PNG, will animate"}
    ], "recommendations":[], "nextSteps":[] } ],
  "devNotes": [], "persistentElementNames": ["Logo"] }, "errors": [] }
//… frames[] trimmed 11→1, elements trimmed to 4

return reply({
  ok: true,
  overviewImagePath,
  frameRenders,
  errors,
  note: overviewImagePath
    ? 'overviewImagePath is the full page — Read it for captions/flow; frameRenders are per-screen.'
    : 'No page overview resolved; frame renders only.',
});

packages/autolens-agent/src/tools/captureFigmaStoryboard.ts:119-127 (literal return shape)

{ "ok": true, "overviewImagePath": "figma-cache/EXAMPLE_FILE_KEY/renders/0_1.png",
  "frameRenders": { "146:308": ".../renders/146_308.png", "146:98": ".../renders/146_98.png" },
  "errors": [] }

Pipeline: Phase 0 (0b)

export interface PlannerResult {
  success: boolean;
  brief?: LensBrief;
  briefPath?: string;
  summary?: string;
  openQuestions?: string[];
  openQuestionOptions?: string[][];
  error?: string;
  validationErrors?: string[];
  partial?: boolean; //true when the run ended without plan_finalize succeeding
  turns: number;
}
export interface LensBrief {
  schemaVersion: 1;
  lens: { name: string; genre: LensGenre; mode: 'selfie'|'world'|'common'; figmaFileKey: string; storyboardPage?: string };
  features: LensBriefFeature[];
  flow: { start: string; transitions: LensBriefTransition[] };
  scoring?: LensBriefScoring;
  interactions: LensBriefInteraction[];
  hints?: LensBriefHint[];
  openQuestions: string[]; //unknowns surfaced for the user — NEVER guessed silently
  openQuestionOptions?: string[][];
  resolvedDecisions?: LensBriefResolvedDecision[];
  entranceAnimations?: LensBriefEntranceAnimation[];
}

packages/autolens-agent/src/planner/runPlannerAgent.ts:21-35 (PlannerResult); src/lib/agent/lensBrief/types.ts:164-201 (LensBrief; features :76-98, transitions :102-111, scoring :113-129, variantSets :65-74)

{ "schemaVersion":1, "lens":{"name":"Visa Fan Type","genre":"personality-quiz","mode":"selfie",
    "figmaFileKey":"EXAMPLE_FILE_KEY"},
  "features":[
    {"name":"Question1","controller":"Question1Controller","kind":"family","layoutFrame":"146:98",
     "questionFlow":{"model":"single-screen","textSwapOnly":true}},
    {"name":"FanReveal","controller":"FanRevealController","kind":"family",
     "frames":["146:308","146:360","146:409","146:462","146:513"],
     "variantSets":[{"slot":"fan-type-display","variants":["fan_type_1","…","fan_type_5"],
       "drivenBy":"scoreBucket","default":"fan_type_1"}]}],
  "flow":{"start":"Question1","transitions":[{"from":"Question1","to":"Question2","trigger":"answerCommitted","transitionStyle":"fade"}]},
  "scoring":{"model":"bit-index","outcomes":5,"surpriseChance":0.1},
  "interactions":[{"feature":"Question1","kind":"tilt-to-select","inputModel":"both","feelTunables":{"tiltThreshold":0.35}}],
  "openQuestions":["Should the fan type persist to the camera-roll caption?"] }

Glossary: BuildManifest vs Lens Brief · Pipeline: Phase 0

export interface BuildManifest {
  schemaVersion: typeof MANIFEST_SCHEMA_VERSION;
  lensMode: 'selfie' | 'world' | 'common';
  template: 'thearlab' | 'none';
  assets: BuildManifestAsset[];
  layers: BuildManifestLayer[];
  groups?: BuildManifestGroup[];
  scripts?: BuildManifestScript[];
  wiring?: BuildManifestWiring[];
}
export interface BuildManifestAsset {
  id: string; type: AssetType; source: AssetSource; name: string;
  figmaNodeId?: string; prompt?: string; path?: string; preset?: string;
}
export interface BuildManifestLayer {
  id: string; name: string; type: LayerType; anchor: AnchorRect;
  frame: FrameSlot; cameraLayer: CameraSlot; groupId?: string; renderOrder?: number;
  //…persistent/reuse/variantSlot/drivenBy/hint/animation fields trimmed
  assetRef?: string; stretchMode?: number; tintColor?: string; opacity?: number;
  flipX?: boolean; flipY?: boolean; expectedAspect?: number;
  text?: string; fontSize?: number; fontFamily?: string; textColor?: string; textAlignment?: TextAlignment;
}

src/lib/agent/lensBrief/manifest.ts:170-179 (BuildManifest); :41-55 (BuildManifestAsset); :58-129 (BuildManifestLayer)

{ "schemaVersion":1, "lensMode":"selfie", "template":"thearlab",
  "assets":[{"id":"q1_card","type":"texture","source":"figma","name":"Q1 Question Card","figmaNodeId":"146:120"}],
  "layers":[
    {"id":"question_card","name":"Q1 Question Card","type":"image","assetRef":"q1_card","frame":"safe",
     "cameraLayer":"main","anchor":{"left":-0.8,"right":0.8,"bottom":0.2,"top":0.7},"stretchMode":2,"expectedAspect":1.4},
    {"id":"catchphrase","name":"Catchphrase","type":"text","text":"You, my friend, are a","fontFamily":"Inter",
     "fontSize":20,"textColor":"#ffffff","frame":"safe","cameraLayer":"main",
     "anchor":{"left":-0.76,"right":0.76,"bottom":0.1,"top":0.18}}] }

Glossary: BuildManifest vs Lens Brief · Pipeline: Phase 0 (0d)

return reply({
  textureMap, fontCache, errors, installed: Object.keys(textureMap).length, total: rawAssets.length,
  organized: moved.size, reused, resolvedVariantSlots, variantSetErrors,
});

packages/autolens-agent/src/tools/materializeAssets.ts:277-280 (literal return shape — wider than the old doc, also organized/resolvedVariantSlots/variantSetErrors)

{ "textureMap":{"q1_card":"06505b2e-8561-4074-b01e-515d43bc7833","q1_tilt_hint":"d6f0b7fe-548f-42bd-bf82-c381a62e12bf"},
  "fontCache":{"Inter":"b1e0…-font-uuid"}, "errors":[], "installed":2,"total":2,"organized":2,"reused":0,
  "resolvedVariantSlots":[{"slot":"fan-type-display","drivenBy":"scoreBucket",
    "variantTextureUUIDs":["59eefac8-…","254a1c45-…"],"defaultIndex":0}], "variantSetErrors":[] }

Pipeline: Phase 1

return result({
  ok: errors.length === 0,
  applied: applied.applied ?? 0,
  errors,
  idMapping,
  anchorsSet,
  created: (instructions.create ?? []).length,
  modified: Object.keys(instructions.modify ?? {}).length,
  deleted: (instructions.delete ?? []).length,
  skippedAsExisting,
  aspectChecks,
  validationWarnings: v.warnings,
  //…flowBlind fields trimmed
});
//idMapping KEY forms: SceneObject "$temp:so_<layerId>" (applyInstructions.ts:101,183)
//                      component  "$temp:so_<layerId>:<Type>#0" (manifest.ts:692)

packages/autolens-agent/src/tools/buildFromManifest.ts:284-297 (literal return shape); src/lib/build/applyInstructions.ts:101,183; src/lib/agent/lensBrief/manifest.ts:692

{ "ok":true,"applied":6,"errors":[],
  "idMapping":{
    "$temp:so_question_card":"a3f01c2e-…","$temp:so_question_card:ScreenTransform#0":"b7c92d40-…",
    "$temp:so_question_card:Image#0":"c1d83e50-…","$temp:so_catchphrase":"d2e94f60-…",
    "$temp:so_catchphrase:ScreenTransform#0":"e3fa5071-…"},
  "anchorsSet":2,"created":2,"modified":0,"deleted":0,"skippedAsExisting":["Logo"],
  "aspectChecks":[{"sceneObjectUUID":"a3f01c2e-…","expectedAspect":1.4}],"validationWarnings":[] }

Glossary: VirtualScene apply · Pipeline: Phase 2

//derivedFacts.ts — facts.json shape
export interface DerivedFact { key: string; value: unknown; at: string; }
interface FactsFile { schemaVersion: 1; facts: DerivedFact[]; }

//buildFigmaFrame.ts — literal return shape
return reply({
  ok: errors.length === 0, results, errors, summary, log,
  factsFile: FACTS_RELATIVE_PATH,
  factsNote: `Resolved node ids + constants were appended to ${FACTS_RELATIVE_PATH}…`,
  nextSteps: ['verify_geometry', 'verify_layer', 'verify_render_order'],
});

packages/autolens-agent/src/tools/derivedFacts.ts:9-18 (facts.json shape); buildFigmaFrame.ts:283-290 (return), :261-267 (facts keys written); FrameBuildResult/BuiltElement in figmaFrameBuilder.ts

{ "schemaVersion":1, "facts":[
  {"key":"frame:Question 1","value":{"nodeId":"146:98","width":334,"height":732,"aspectK":0.8112},"at":"…"},
  {"key":"container:Question 1","value":{"sceneObjectUUID":"f1a0…","name":"Question 1","parentRegion":"safe"},"at":"…"},
  {"key":"feature-container:Question1","value":{"name":"Question 1","sceneObjectUUID":"f1a0…"},"at":"…"},
  {"key":"element:Question 1:Q1 Question Card","value":{"figmaNodeId":"146:120",
    "sceneObjectUUID":"a3f01c2e-…","textureUUID":"06505b2e-8561-4074-b01e-515d43bc7833"},"at":"…"}]}

Glossary: facts.json · Pipeline: Phase 2

export interface WiredFeatureReport {
  feature: string; controller: string;
  scriptAssetUUID: string | null; scriptComponentUUID: string | null;
  boundInputs: string[]; unboundInputs: string[]; todos: string[];
  //container → 'arg' | 'facts:feature' | 'facts:frame' | 'brief:frame' | 'feature-name';
  //each element @input name → 'subtree' | 'global' | 'ambiguous' | 'missing'
  resolvedVia: Record<string, string>;
}
export interface WireFlowReport {
  success: boolean; features: WiredFeatureReport[];
  hub: { updatedInPlace: boolean; scriptPath: string | null; refsWired: string[]; refsPending: string[]; todos: string[] };
  recompile: { ran: boolean; note?: string };
  verify: { ran: boolean; logErrors: string[] };
  defects: string[]; nextSteps: string[];
}

src/lib/build/screenFlow/wire.ts:75-87 (WiredFeatureReport), :89-103 (WireFlowReport); resolvedVia values documented :83-85

{ "success":true, "features":[
  {"feature":"Question1","controller":"Question1Controller","scriptComponentUUID":"7b2f…",
   "boundInputs":["questionCard","answerLeft","answerRight","tiltHint"],"unboundInputs":[],"todos":[],
   "resolvedVia":{"container":"facts:feature","questionCard":"subtree","answerLeft":"subtree","tiltHint":"global"}}],
  "hub":{"updatedInPlace":true,"refsWired":["Question1Controller"]},"recompile":{"ran":true},"defects":[] }

Glossary: wire_screen_flow / wiring / resolvedVia · Pipeline: Phase 2 (2e)

verify_semantics

interface SemanticDefect { severity: 'critical' | 'warning'; check: string; detail: string; }
//return: {ok, defects: SemanticDefect[]}
//real check names: inputTypeCheck | inputNamesNonEmpty | layerMask | aspectMismatch | textureLiveness | icHitArea

packages/autolens-agent/src/tools/verifySemantics.ts:17-21

{ "ok":false,"defects":[{"severity":"critical","check":"layerMask",
  "detail":"\"tilt-hint\" has layers=1048576, expected 2 — present in the scene, invisible on the camera that should show it."}] }

verify_geometry

const pass = matched > 0 && matched >= requested && residuals.length === 0 && groupOffsetResults.length === 0;
//return: {checked, matched, requested, layerSource, corrected[], residuals[], unmatched[], groupOffsetDefects[], pass}
//pass is always false on matched:0 — a soft "0 matched" note used to look like a pass; it can't anymore

packages/autolens-agent/src/tools/verifyGeometry.ts:345-351 (return shape), :338 (pass invariant)

{ "checked":4,"matched":4,"requested":4,"layerSource":"facts",
  "corrected":[{"name":"Q1 Question Card","builtWidthPct":52.0,"figmaWidthPct":63.0,"deltaWidthPct":11.0}],
  "residuals":[],"unmatched":[],"groupOffsetDefects":[],"pass":false }

verify_behavior

interface InteractionResult { name: string; passed: boolean; observedState: string | null; detail: string; }
//return: {ok, results: InteractionResult[]}

packages/autolens-agent/src/tools/verifyBehavior.ts:45-49

{ "ok":true,"results":[{"name":"tilt left to pick answer","passed":true,
  "observedState":"Question2","detail":"state advanced to expected 'Question2' after gesture"}] }

Glossary: the verify_* gates · Pipeline: Phase 4