feat: compose semantic Plainform hero shots

Author: SamG-Coder

src/plainform/composition-plainform-compiler.mjs

@@ -0,0 +1,48 @@
+const clean = value => value.trim().replace(/[.;]+$/u, '').trim();
+const slug = value => clean(value).toLowerCase().replace(/^(?:the|a|an)\s+/u, '').replace(/[^a-z0-9]+/gu, '-').replace(/^-+|-+$/gu, '');
+function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
+function resolveSubject(scene, value) {
+  const wanted = slug(value); const matches = Object.values(scene.entities).filter(entity => entity.id === clean(value) || slug(entity.name) === wanted || slug(entity.id.split('/').at(-1)) === wanted);
+  if (matches.length !== 1) fail(matches.length ? 'plainform_composition_subject_ambiguous' : 'plainform_composition_subject_missing', `Composition subject “${value}” must resolve exactly once.`);
+  return matches[0];
+}
+const lensFov = millimetres => 2 * Math.atan(36 / (2 * millimetres)) * 180 / Math.PI;
+
+export class CompositionPlainformCompiler {
+  compile(source, { project } = {}) {
+    const scene = project?.scenes?.[project.activeSceneId]; if (!scene) fail('plainform_project_required', 'Composition Plainform requires an active scene.');
+    const match = source.replace(/\s+/gu, ' ').trim().match(/^frame the whole (.+?) from (slightly below|eye level|slightly above) at a (\d+(?:\.\d+)?) millimetre lens\. use late afternoon sun from camera left, soft blue sky fill, a (.+?) ground, and enough depth of field to keep the (.+?) and (.+?) sharp\.?$/iu);
+    if (!match) fail('plainform_composition_unsupported', 'Use the bounded hero-composition sentence with subject, angle, lens, ground, and sharp semantic extents.');
+    const subject = resolveSubject(scene, match[1]); const lens = Number(match[3]); if (!(lens >= 12 && lens <= 300)) fail('plainform_composition_lens', 'Composition lens must be 12 to 300 millimetres.');
+    const compositionSlug = slug(subject.name); const cameraId = scene.settings.activeCameraId ?? `camera/composition/${compositionSlug}`;
+    const rigId = `entity/composition/${compositionSlug}/light-rig`; const groundId = `entity/composition/${compositionSlug}/ground`;
+    const groundGeometryId = `geometry/composition/${compositionSlug}/ground`; const groundMaterialId = `material/composition/${compositionSlug}/ground`;
+    const assetId = `asset/composition/${compositionSlug}`; const elevation = ({ 'slightly below': -0.12, 'eye level': 0, 'slightly above': 0.18 })[match[2].toLowerCase()];
+    const diagnostics = [
+      { code: 'PLAINFORM_COMPOSITION_DOF_FALLBACK', severity: 'information', hosts: ['native', 'browser'], message: 'Depth-of-field intent is stored canonically; raster preview keeps the resolved trunk-to-crown focus range sharp without a post-process blur.' },
+      { code: 'PLAINFORM_COMPOSITION_ENVIRONMENT_FALLBACK', severity: 'information', hosts: ['browser'], message: 'Browser preview uses the same outdoor light entities and linear background; environment importance sampling remains a native capability difference.' },
+    ];
+    const presentation = {
+      formatVersion: 1, kind: 'presentation', subject: { entityId: subject.id, semanticBounds: ['whole', slug(match[5]), slug(match[6])] },
+      camera: { cameraId, angle: match[2].toLowerCase(), lensMillimetres: lens, fieldOfViewDegrees: lensFov(lens), lookTarget: 'semantic-bounds-center', aspect: 16 / 9 },
+      lighting: { rigId, timeOfDay: 'lateAfternoon', key: { role: 'sun', direction: 'cameraLeft', unit: 'lux', illuminance: 32000 }, fill: { role: 'sky', color: [0.45, 0.65, 1], unit: 'relative', intensity: 0.75 } },
+      environment: { ground: { entityId: groundId, description: clean(match[4]) }, backdrop: 'softBlueSky', fog: { mode: 'linear', near: 80, far: 450 }, exposure: 1 },
+      depthOfField: { mode: 'semanticRange', nearSemantic: slug(match[5]), farSemantic: slug(match[6]), fallback: 'keep-range-sharp' }, diagnostics,
+    };
+    const operations = [];
+    const createResources = [];
+    if (!project.resources.geometries?.[groundGeometryId]) createResources.push({ resourceType: 'geometries', resource: { id: groundGeometryId, recipe: { kind: 'box', width: 30, height: 0.1, depth: 30 } } });
+    if (!project.resources.materials?.[groundMaterialId]) createResources.push({ resourceType: 'materials', resource: { id: groundMaterialId, recipe: { kind: 'physical', color: '#8a7a49', roughness: 0.96, metalness: 0 } } });
+    if (!project.resources.assets?.[assetId]) createResources.push({ resourceType: 'assets', resource: { id: assetId, kind: 'presentation', name: `${subject.name} Hero Composition`, presentation } });
+    if (createResources.length) operations.push({ op: 'resource.createMany', items: createResources });
+    else operations.push({ op: 'resource.patch', resourceType: 'assets', resourceId: assetId, patch: { presentation } });
+    if (!scene.entities[cameraId]) operations.push({ op: 'entity.create', sceneId: scene.id, entity: { id: cameraId, kind: 'perspectiveCamera', name: `${subject.name} Hero Camera`, components: { camera: { fov: lensFov(lens), near: 0.1, far: 1000 } }, metadata: { compositionAssetId: assetId } } });
+    else operations.push({ op: 'entity.patch', entityId: cameraId, patch: { components: { camera: { ...scene.entities[cameraId].components?.camera, fov: lensFov(lens) } }, metadata: { ...scene.entities[cameraId].metadata, compositionAssetId: assetId } } });
+    if (!scene.entities[groundId]) operations.push({ op: 'entity.create', sceneId: scene.id, entity: { id: groundId, kind: 'mesh', name: `${clean(match[4])} ground`, transform: { position: [0, -0.05, 0], rotation: [0, 0, 0], scale: [1, 1, 1] }, components: { mesh: { geometryId: groundGeometryId, materialId: groundMaterialId } }, metadata: { compositionAssetId: assetId } } });
+    if (!scene.entities[rigId]) operations.push({ op: 'lighting.rig.create', sceneId: scene.id, rigId, preset: 'outdoor', center: [0, 0, 0], scale: 1, intensity: 1, rtx: 'auto' });
+    operations.push({ op: 'camera.frame', cameraId, target: { targetIds: [subject.id] }, aspect: 16 / 9, padding: 1.12, view: { azimuth: -0.55, elevation, distanceScale: 1.15, targetOffset: [0, 0, 0], minHeight: 0.2 }, lockPreviewAspect: true });
+    operations.push({ op: 'scene.setActiveCamera', sceneId: scene.id, cameraId });
+    operations.push({ op: 'scene.settings.patch', sceneId: scene.id, patch: { background: { mode: 'color', color: [0.32, 0.52, 0.78], colorSpace: 'linear-srgb' }, fog: { mode: 'linear', color: [0.42, 0.58, 0.76], near: 80, far: 450 }, presentation: { assetId, exposure: 1, depthOfField: presentation.depthOfField } } });
+    return Object.freeze({ language: 'plainform-v1', dialect: 'composition', source, operations: Object.freeze(operations), interpretation: Object.freeze([`Frame ${subject.id} at ${lens} mm from ${match[2].toLowerCase()}.`, 'Create a typed late-afternoon outdoor presentation with explicit host fallbacks.']), aliases: Object.freeze({}), requestedPreview: true, composition: Object.freeze({ assetId, cameraId, subjectId: subject.id, diagnostics: Object.freeze(diagnostics) }) });
+  }
+}

src/plainform/index.mjs

@@ -7,6 +7,7 @@ export { PlainformPrefabContext } from './prefab-context.mjs';
 export { ShaderPlainformCompiler, ShaderPlainformError } from './shader-plainform-compiler.mjs';
 export { EventPlainformCompiler } from './event-plainform-compiler.mjs';
 export { FormPlainformCompiler } from './form-plainform-compiler.mjs';
+export { CompositionPlainformCompiler } from './composition-plainform-compiler.mjs';
 export { interpretShaderFeel, SHADER_FEEL_VOCABULARY } from './shader-feel-vocabulary.mjs';
 export { DesignPlainformCompiler } from './design-plainform-compiler.mjs';
 export { DesignExpressionError, evaluateDesignExpression, evaluateDesignVector } from './design-expression.mjs';

src/plainform/plainform-compiler.mjs

@@ -10,6 +10,7 @@ import { ShaderPlainformCompiler } from './shader-plainform-compiler.mjs';
 import { DesignPlainformCompiler } from './design-plainform-compiler.mjs';
 import { EventPlainformCompiler } from './event-plainform-compiler.mjs';
 import { FormPlainformCompiler } from './form-plainform-compiler.mjs';
+import { CompositionPlainformCompiler } from './composition-plainform-compiler.mjs';
 import { parsePlainformProgram } from './plainform-front-end.mjs';
 
 const TAU = Math.PI * 2;
@@ -368,6 +369,7 @@ export class PlainformCompiler {
     if (program.dialect === 'design') return new DesignPlainformCompiler().compile(source, { project });
     if (program.dialect === 'event') return new EventPlainformCompiler().compile(source, { project });
     if (program.dialect === 'form') return new FormPlainformCompiler().compile(source, { project });
+    if (program.dialect === 'composition') return new CompositionPlainformCompiler().compile(source, { project });
     if (!project) fail('plainform_project_required', 'Plainform compilation requires the canonical project document.');
     const statements = source.split(/\r?\n/u).map(cleanStatement).filter(Boolean);
     if (statements.length > MAX_STATEMENTS) fail('plainform_statement_limit', `Plainform accepts at most ${MAX_STATEMENTS} statements.`);

src/plainform/plainform-front-end.mjs

@@ -361,6 +361,13 @@ const DEFINITIONS = Object.freeze([
     examples: ['Create a modal Save Game dialog with a multiline notes box. Enter adds a line; Control+Enter confirms only when a slot is selected.'],
     semanticKey: match => `form.${semanticPart(match[1])}`, fields: match => ({ name: match[1], notesField: match[2] }),
   }),
+  definition({
+    id: 'composition.hero', dialect: 'composition', domain: 'composition', kind: 'composition.heroFrame', priority: 900,
+    pattern: /^frame the whole (.+?) from (slightly below|eye level|slightly above) at a (\d+(?:\.\d+)?) millimetre lens\. use late afternoon sun from camera left, soft blue sky fill, a (.+?) ground, and enough depth of field to keep the (.+?) and (.+?) sharp$/iu,
+    summary: 'Create a bounded semantic hero composition with camera, outdoor rig, ground, atmosphere, and explicit fallbacks.', inputs: ['subject', 'angle', 'lens', 'ground', 'nearSemantic', 'farSemantic'], outputs: ['presentation', 'camera', 'lightRig'],
+    examples: ['Frame the whole pine from slightly below at a 50 millimetre lens. Use late afternoon sun from camera left, soft blue sky fill, a dry grass ground, and enough depth of field to keep the trunk and crown sharp.'],
+    semanticKey: match => `composition.${semanticPart(match[1])}.hero`, fields: match => ({ subject: match[1], angle: match[2], lensMillimetres: Number(match[3]), ground: match[4], nearSemantic: match[5], farSemantic: match[6] }),
+  }),
   definition({
     id: 'shader.property.set', dialect: 'shader', domain: 'shader', kind: 'shader.setProperty',
     pattern: /^(?:set|drive) (?:the )?(.+?) (?:to|with) (.+)$/iu,
@@ -377,6 +384,7 @@ function inferDialect(source) {
   if (/^\s*(?:begin\s+)?design\b/iu.test(source)) return 'design';
   if (/^\s*(?:for .+?,\s*when |when (?:the )?.+? (?:collides|receives|is destroyed))/imu.test(source)) return 'event';
   if (/^\s*create (?:an? .+? window|a modal .+? dialog)\b/imu.test(source)) return 'form';
+  if (/^\s*frame the whole .+? from /imu.test(source)) return 'composition';
   return 'object';
 }
 

tests/composition-plainform.test.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createProjectDocument } from '../src/core/index.mjs';
+import { operationSchema } from '../src/mcp/tool-schemas.mjs';
+import { PlainformCompiler } from '../src/plainform/index.mjs';
+
+function project() {
+  return createProjectDocument({
+    projectId: 'project/composition',
+    scenes: [{ id: 'scene/main', entities: [
+      { id: 'entity/pine', kind: 'group', name: 'Pine', children: ['entity/pine/trunk', 'entity/pine/crown'] },
+      { id: 'entity/pine/trunk', kind: 'mesh', name: 'Trunk', parentId: 'entity/pine', components: { mesh: { geometryId: 'geometry/trunk' } } },
+      { id: 'entity/pine/crown', kind: 'mesh', name: 'Crown', parentId: 'entity/pine', transform: { position: [0, 7, 0] }, components: { mesh: { geometryId: 'geometry/crown' } } },
+    ] }],
+    resources: { geometries: [
+      { id: 'geometry/trunk', recipe: { kind: 'cylinder', radius: 0.5, height: 8 } },
+      { id: 'geometry/crown', recipe: { kind: 'sphere', radius: 3 } },
+    ] },
+  });
+}
+
+const source = 'Frame the whole pine from slightly below at a 50 millimetre lens. Use late afternoon sun from camera left, soft blue sky fill, a dry grass ground, and enough depth of field to keep the trunk and crown sharp.';
+
+test('Composition Plainform lowers one semantic hero sentence to typed camera, lighting, ground, and appearance operations', () => {
+  const compiled = new PlainformCompiler().compile(source, { project: project() });
+  assert.equal(compiled.dialect, 'composition');
+  assert.equal(compiled.requestedPreview, true);
+  assert.ok(compiled.operations.every(operation => operationSchema.safeParse(operation).success));
+  const frame = compiled.operations.find(operation => operation.op === 'camera.frame');
+  assert.deepEqual(frame.target, { targetIds: ['entity/pine'] });
+  assert.equal(frame.view.elevation, -0.12);
+  const rig = compiled.operations.find(operation => operation.op === 'lighting.rig.create');
+  assert.equal(rig.preset, 'outdoor');
+  const settings = compiled.operations.find(operation => operation.op === 'scene.settings.patch').patch;
+  assert.equal(settings.fog.mode, 'linear');
+  assert.equal(settings.presentation.depthOfField.mode, 'semanticRange');
+  const resources = compiled.operations[0].items.map(item => item.resource);
+  const presentation = resources.find(resource => resource.kind === 'presentation').presentation;
+  assert.deepEqual(presentation.subject.semanticBounds, ['whole', 'trunk', 'crown']);
+  assert.ok(Math.abs(presentation.camera.fieldOfViewDegrees - 39.5978) < 0.001);
+});
+
+test('Composition Plainform is deterministic across hosts and documents explicit renderer differences', () => {
+  const first = new PlainformCompiler().compile(source, { project: project() });
+  const second = new PlainformCompiler().compile(source, { project: project() });
+  assert.deepEqual(first.operations, second.operations);
+  assert.deepEqual(first.composition.diagnostics.map(item => item.code), [
+    'PLAINFORM_COMPOSITION_DOF_FALLBACK',
+    'PLAINFORM_COMPOSITION_ENVIRONMENT_FALLBACK',
+  ]);
+  assert.deepEqual(first.composition.diagnostics[1].hosts, ['browser']);
+});
+
+test('Composition Plainform rejects ambiguous subjects and unsafe lenses before mutation', () => {
+  const duplicate = project(); duplicate.scenes['scene/main'].entities['entity/other-pine'] = { ...duplicate.scenes['scene/main'].entities['entity/pine'], id: 'entity/other-pine', children: [], name: 'Pine' };
+  assert.throws(() => new PlainformCompiler().compile(source, { project: duplicate }), error => error.code === 'plainform_composition_subject_ambiguous');
+  assert.throws(() => new PlainformCompiler().compile(source.replace('50 millimetre', '5 millimetre'), { project: project() }), error => error.code === 'plainform_composition_lens');
+});