Site massing

Build a browser-based site massing app with @opengeometry/floorkit.
Read https://docs.ploterr.com/llms.txt and
https://docs.ploterr.com/floorkit/playbooks/site-massing.md first.
Check the installed version and index.d.ts for the APIs used in this playbook.
If an API is missing, report it before implementing an alternative.

Reproduce the playbook's 30 × 20 m parcel at flat grade Y = 0:
a retail podium with a residential tower and a separate four-storey building.
Use the exact model, authored IDs, footprints and controls from the recipes.
Label the supplied FAR 0.7, coverage 40%, height 15 m, setbacks 3 m and
separation 4 m as illustrative. Do not invent rules for a real site.

Initialize the geometry kernel once. Keep one ProjectManager for the open
study and connect the plan and 3D editors to it. Apply supported commands
through the manager; preserve IDs and one undo history. Keep geometry in
metres, Y up, with footprint points [x, z]. Validate unknown JSON and check
stale proposals before applying agent edits, following Agent building workflow.

Show quantities, all named zoning violations and visible edit errors.
Verify the two-building baseline: 384 m², FAR 0.64, coverage 24%, height 12 m.
Set the tower part to 9 m: 432 m², FAR 0.72, total height 13 m, exceeds-far.
Undo must restore the baseline. Front setback 5 m must flag both buildings.

Save named options with their editable project, rules and assumptions.
Compare equivalent site/rule bases; flag different bases. Reopen an option,
restore its assumptions and state that saved files do not retain undo history.
Export editable JSON, a site plan PDF, envelope-free GLB and report CSV.
Treat estimated unit counts as arithmetic assumptions, not a physical fit test.

Run and verify locally. Report the package version, assumptions, unresolved
checks and verification results. Follow the hostname licensing requirements
before deploying. Do not claim the example establishes planning approval.

import {
  ProjectManager,
  basicZoningRules,
  evaluateZoning,
  irMassToMassLike,
  massBuildingCommand,
  massSegmentHeightCommand,
  type BuildingModel,
  type ManagedPlanEditor,
  type ProjectFile,
  type ZoningReport,
} from '@opengeometry/floorkit';

export const siteModel: BuildingModel = {
  schema: 'floorkit.building-model',
  version: 3,
  units: 'meters',
  upAxis: 'y',
  id: 'site-study',
  site: {
    id: 'parcel',
    boundary: {
      outerRing: [
        [0, 0],
        [30, 0],
        [30, 20],
        [0, 20],
      ],
    },
    lotLines: ['front', 'side', 'rear', 'side'],
    elevation: 0,
    trueNorthDeg: 0,
    zoning: basicZoningRules({
      id: 'study-controls',
      maxFAR: 0.7,
      maxCoverage: 0.4,
      maxHeight: 15,
      setbacks: { front: 3, side: 3, rear: 3 },
      minSeparation: 4,
      countsTowardFAR: ['gross'],
    }),
  },
  buildings: [
    {
      id: 'podium-tower',
      name: 'Podium and tower',
      storeys: [
        { id: 'ground', elevation: 0, height: 4, usage: 'retail' },
        { id: 'first', elevation: 4, height: 3, usage: 'residential' },
        { id: 'second', elevation: 7, height: 3, usage: 'residential' },
      ],
      mass: {
        id: 'podium-tower-mass',
        elevation: 0,
        segments: [
          {
            id: 'podium',
            name: 'Podium',
            footprint: {
              outerRing: [
                [4, 4],
                [16, 4],
                [16, 12],
                [4, 12],
              ],
            },
            height: 4,
            use: 'retail',
            storeyIds: ['ground'],
          },
          {
            id: 'tower',
            name: 'Tower',
            footprint: {
              outerRing: [
                [6, 5],
                [14, 5],
                [14, 11],
                [6, 11],
              ],
            },
            height: 6,
            use: 'residential',
            storeyIds: ['first', 'second'],
          },
        ],
      },
    },
  ],
};

export const siteProject: ProjectFile = {
  schema: 'floorkit.project',
  version: 3,
  buildingModel: siteModel,
  views: [
    {
      id: 'site-plan',
      name: 'Site massing',
      kind: 'plan',
      storeyId: 'ground',
      cutHeightAboveStorey: 1.2,
      showMassing: true,
    },
  ],
  paper: {
    version: 1,
    unitSystem: 'metric',
    sheets: [
      {
        id: 'site-sheet',
        name: 'Site study',
        number: 'S-01',
        page: {
          format: 'A3',
          orientation: 'landscape',
          size: { width: 420, height: 297 },
          margin: 10,
        },
        viewports: [
          {
            id: 'site-viewport',
            viewId: 'site-plan',
            drawingNumber: '1',
            frame: { x: 20, y: 20, width: 380, height: 245 },
            scale: 0.01,
            rotationDeg: 0,
            clip: true,
            title: { text: 'Site massing', showScale: true },
          },
        ],
        annotations: [],
        titleblock: { templateId: 'default', values: { sheetNumber: 'S-01' } },
      },
    ],
  },
};

export function openStudy(onError?: (error: unknown) => void): ProjectManager {
  const manager = new ProjectManager(siteProject, { onError });
  manager.setBuildableEnvelope(true);
  return manager;
}

export async function mountSitePlan(
  manager: ProjectManager,
  container: HTMLElement,
): Promise<ManagedPlanEditor> {
  return manager.mountPlanEditor(container, 'site-plan');
}

export function addSecondBuilding(manager: ProjectManager): void {
  const command = massBuildingCommand(
    manager.session.snapshot(),
    [
      [20, 4],
      [26, 4],
      [26, 12],
      [20, 12],
    ],
    { name: 'Second building', storeyHeight: 3, storeyCount: 4, use: 'residential' },
  );
  manager.apply(command);
}

export async function drawBuilding(plan: ManagedPlanEditor): Promise<string | undefined> {
  return plan.startMassDrawing({ storeyHeight: 3, storeyCount: 4, use: 'residential' });
}

export function raiseTower(manager: ProjectManager, height: number): void {
  const command = massSegmentHeightCommand(
    manager.session.snapshot(),
    'podium-tower',
    'tower',
    height,
  );
  if (command) manager.apply(command);
}

export function studyReport(manager: ProjectManager): ZoningReport {
  const { site, buildings } = manager.session.snapshot();
  if (!site?.boundary || !site.zoning) throw new Error('The study needs a parcel and controls.');
  const masses = buildings.flatMap((building) =>
    building.mass ? [irMassToMassLike(building)] : [],
  );
  return evaluateZoning(
    { profile: site.boundary, lotLines: site.lotLines, elevation: site.elevation },
    masses,
    site.zoning,
  );
}

export function watchStudy(
  manager: ProjectManager,
  render: (report: ZoningReport) => void,
): () => void {
  render(studyReport(manager));
  return manager.subscribe(() => render(studyReport(manager)));
}

export function setFrontSetback(manager: ProjectManager, metres: number): void {
  const site = manager.session.snapshot().site;
  if (!site?.zoning) throw new Error('The study needs zoning controls.');
  const rules = site.zoning.rules.map((rule) =>
    rule.kind === 'envelope-plane' && rule.edgeClass === 'front'
      ? { ...rule, offsetAtGrade: metres }
      : rule,
  );
  manager.apply({ kind: 'replace-site', site: { ...site, zoning: { ...site.zoning, rules } } });
}

export interface StudyAssumptions {
  residentialEfficiency: number;
  averageUnitArea: number;
}

export const defaultAssumptions: StudyAssumptions = {
  residentialEfficiency: 0.8,
  averageUnitArea: 60,
};

export function residentialEstimate(report: ZoningReport, assumptions = defaultAssumptions) {
  const grossResidentialArea = report.metrics.perMass.reduce(
    (sum, mass) => sum + (mass.grossFloorAreaByUse.residential ?? 0),
    0,
  );
  if (
    !Number.isFinite(assumptions.residentialEfficiency) ||
    assumptions.residentialEfficiency <= 0 ||
    assumptions.residentialEfficiency > 1 ||
    !Number.isFinite(assumptions.averageUnitArea) ||
    assumptions.averageUnitArea <= 0
  )
    throw new Error(
      'Efficiency must be above 0 and at most 1; average unit area must be positive.',
    );
  const estimatedUsableArea = grossResidentialArea * assumptions.residentialEfficiency;
  return {
    grossResidentialArea,
    estimatedUsableArea,
    estimatedUnits: Math.floor(estimatedUsableArea / assumptions.averageUnitArea),
  };
}

export interface StudyOption {
  name: string;
  projectText: string;
  assumptions: StudyAssumptions;
  siteBasis: string;
  report: ZoningReport;
}

export function captureOption(
  manager: ProjectManager,
  name: string,
  assumptions: StudyAssumptions,
): StudyOption {
  const report = studyReport(manager);
  residentialEstimate(report, assumptions);
  return {
    name,
    projectText: manager.save(),
    assumptions: { ...assumptions },
    siteBasis: JSON.stringify(manager.session.snapshot().site),
    report,
  };
}