@pascal-app/editor 1.0.5 → 1.0.7

package/src/lib/lot/drop-in.ts

@@ -9,12 +9,12 @@
  *   3. `sitePatchFromParcel` — the site node patch: ring, address,
  *      provenance, the street-facing front edge, planning-default setbacks
  *      when the site has none, north up.
- *   4. The scene's site node is updated (created at the root when the scene
- *      has none) and a building that fell outside the new ring is
- *      re-centred on it — `building.position` only, never the walls.
- *   5. `elevation` — USGS ground over the lot into the site's
+ *   4. `elevation` — USGS ground over the lot into the site's
  *      heightfield (`site.terrain`, terrain.ts; fail-soft, flat lots write
  *      nothing), so a foundation can read the hill.
+ *   5. The parcel and terrain are applied to the current site together
+ *      (created at the root when the scene has none). A building outside
+ *      the new ring is re-centred — `building.position` only, never the walls.
  *
  * Used by the Lot rail panel, the Generate panel (drop in, then generate)
  * and the Site inspector's "Find parcel", so every path behaves the same.
@@ -271,71 +271,63 @@ export async function dropInLot(
     roadsFailure = 'skipped'
   }
 
-  const scene = useScene.getState()
-  let site = findSiteNode(options.siteId)
-  if (!site) {
-    site = SiteNode.parse({ id: generateId('site'), type: 'site', name: 'Site' })
-    scene.createNodes([{ node: site as AnyNode }])
-  }
-  const computed = sitePatchFromParcel(site, input, data, roads, undefined, extras)
-  if (!computed)
+  const geometry = sitePatchFromParcel(null, input, data, roads, undefined, extras)
+  if (!geometry)
     return {
       ok: false,
       error: 'parcel geometry was unusable',
       message: 'The parcel geometry was unusable.',
     }
-  // the surveyed contour lines ride the site with the patch (the site plan
-  // draws them over the heightfield's own); absent without 3DEP lines
-  const contours = dossier && dossierOrigin ? contourLinesFromDossier(dossier, dossierOrigin) : null
-  useScene
-    .getState()
-    .updateNode(
-      site.id as AnyNodeId,
-      { ...computed.patch, terrainContours: contours ?? undefined } as Partial<AnyNode>,
-    )
-
   // The ground over the lot — fail-soft. A sloping lot writes the
   // heightfield; a flat one (or a failed read) clears any terrain the
   // previous lot left behind so the site never shows another parcel's hill.
   let terrain: TerrainSampleSummary | null = null
   let terrainFailure = ''
+  let terrainRead: TerrainSampleResult | null = null
   if (options.terrain !== false) {
-    const read: TerrainSampleResult = data.originLngLat
-      ? await sampleLotTerrain(computed.patch.polygon?.points ?? [], data.originLngLat, {
+    terrainRead = data.originLngLat
+      ? await sampleLotTerrain(geometry.patch.polygon?.points ?? [], data.originLngLat, {
           provider,
           ...(options.terrainDeadlineMs ? { deadlineMs: options.terrainDeadlineMs } : {}),
         })
       : { ok: false, reason: 'no parcel origin' }
-    const current = useScene.getState().nodes[site.id as AnyNodeId]
-    const { terrainSample: _previous, ...meta } =
-      current &&
-      typeof current.metadata === 'object' &&
-      current.metadata !== null &&
-      !Array.isArray(current.metadata)
-        ? (current.metadata as Record<string, unknown>)
-        : {}
-    if (read.ok && read.summary) {
-      terrain = read.summary
-      useScene.getState().updateNode(
-        site.id as AnyNodeId,
-        {
-          terrain: read.terrain,
-          metadata: { ...meta, terrainSample: read.summary },
-        } as unknown as Partial<AnyNode>,
-      )
-    } else {
-      terrainFailure = read.reason ?? 'no terrain'
-      useScene
-        .getState()
-        .updateNode(
-          site.id as AnyNodeId,
-          { terrain: undefined, metadata: meta } as unknown as Partial<AnyNode>,
-        )
-    }
+    if (terrainRead.ok && terrainRead.summary) terrain = terrainRead.summary
+    else terrainFailure = terrainRead.reason ?? 'no terrain'
   } else {
     terrainFailure = 'skipped'
   }
 
+  // Hydration or a person's edit can replace the site while the providers run.
+  // Read it after every await, preserve its current settings, and commit the
+  // parcel with its terrain so a late read cannot leave the starter polygon.
+  const scene = useScene.getState()
+  let site = findSiteNode(options.siteId)
+  const computed = sitePatchFromParcel(site, input, data, roads, undefined, extras)
+  if (!computed)
+    return {
+      ok: false,
+      error: 'parcel geometry was unusable',
+      message: 'The parcel geometry was unusable.',
+    }
+  const contours = dossier && dossierOrigin ? contourLinesFromDossier(dossier, dossierOrigin) : null
+  const patch: Partial<SiteNode> = {
+    ...computed.patch,
+    terrainContours: contours ?? undefined,
+  }
+  if (terrainRead) {
+    const { terrainSample: _previous, ...metadata } = computed.patch.metadata as Record<
+      string,
+      unknown
+    >
+    patch.terrain = terrainRead.ok ? terrainRead.terrain : undefined
+    patch.metadata = terrain ? { ...metadata, terrainSample: terrain } : metadata
+  }
+  if (site) scene.updateNode(site.id as AnyNodeId, patch as Partial<AnyNode>)
+  else {
+    site = SiteNode.parse({ id: generateId('site'), type: 'site', name: 'Site', ...patch })
+    scene.createNodes([{ node: site as AnyNode }])
+  }
+
   // A house the new lot leaves past its lines stands centred on the buildable area again, facing
   // as it did.
   let recentred = false

package/src/lib/material-swatch-style.ts

@@ -0,0 +1,24 @@
+import type { MaterialSwatch } from '@pascal-app/core'
+import type { CSSProperties } from 'react'
+
+/**
+ * The CSS that paints a material swatch: the image over its colour, and a tinted
+ * albedo multiplied by the colour, as the 3D material tints its map.
+ */
+export function materialSwatchStyle({
+  color,
+  imageUrl,
+  tinted,
+}: Pick<MaterialSwatch, 'color' | 'imageUrl'> & { tinted?: boolean }): CSSProperties {
+  return {
+    backgroundColor: color,
+    ...(imageUrl
+      ? {
+          backgroundImage: `url(${JSON.stringify(imageUrl)})`,
+          backgroundPosition: 'center',
+          backgroundSize: 'cover',
+          ...(tinted ? { backgroundBlendMode: 'multiply' } : {}),
+        }
+      : {}),
+  }
+}

package/src/lib/measurement-parser.ts

@@ -1,6 +1,7 @@
 // Must precede the lingo import: lingo clones its kind table with
 // structuredClone while its module body evaluates. See the file's own comment.
 import './structured-clone-fallback'
+import { normalizeDecimalInput } from '@pascal-app/core'
 import { type Kind, parseQuantity, quantity } from '@pascal-app/lingo'
 
 /**
@@ -56,6 +57,8 @@ export interface ParseMeasurementOptions {
   bareUnit?: string
   /** Disambiguates gal/ton/cup families; harmless for length/angle. */
   system?: 'metric' | 'us' | 'imperial'
+  /** Locale whose decimal separator is accepted in bare values and quantities. */
+  locale?: string
 }
 
 /**
@@ -68,7 +71,7 @@ export function parseMeasurement(
   spec: LingoUnitSpec,
   options: ParseMeasurementOptions = {},
 ): number | null {
-  const result = parseQuantity(raw, {
+  const result = parseQuantity(normalizeDecimalInput(raw, options.locale), {
     kind: spec.kind,
     unit: options.bareUnit ?? spec.unitId,
     system: options.system,
@@ -105,9 +108,10 @@ export function measurementHint(
   options: MeasurementHintOptions = {},
 ): string | null {
   const trimmed = raw.trim()
-  if (!trimmed || PLAIN_NUMBER.test(trimmed)) return null
+  const normalized = normalizeDecimalInput(trimmed, options.locale)
+  if (!normalized || PLAIN_NUMBER.test(normalized)) return null
 
-  const parsed = parseMeasurement(trimmed, spec, options)
+  const parsed = parseMeasurement(normalized, spec, options)
   if (parsed === null) return null
   const stored = options.clamp ? options.clamp(parsed) : parsed
 

package/src/lib/measurements.test.ts

@@ -18,6 +18,7 @@ import {
   measurementFloorplanPresentationColor,
   measurementPresentationColor,
   metersToLinearUnit,
+  parseLinearMeasurementInput,
   squareMetersToAreaUnit,
 } from './measurements'
 
@@ -129,6 +130,11 @@ describe('linear measurements', () => {
     expect(linearControlValueToMeters(3.5, 'metric')).toBe(3.5)
   })
 
+  test('parses floor-plan measurement input with the scoped locale', () => {
+    expect(parseLinearMeasurementInput('2,75', 'metric', 'fr')).toBe(2.75)
+    expect(parseLinearMeasurementInput('2,75', 'metric', 'en')).toBeNull()
+  })
+
   test('clamps numeric control input after converting to meters', () => {
     expect(linearControlValueToMeters(0.1, 'imperial', { minMeters: 0.1 })).toBe(0.1)
     expect(linearControlValueToMeters(0.3, 'imperial', { minMeters: 0.1 })).toBe(0.1)
@@ -212,4 +218,15 @@ describe('typed measurement fields', () => {
     expect(measurementHint('180cm', length)).toBe('= 1.80 m')
     expect(measurementHint('6', length)).toBeNull()
   })
+
+  test('only treats the active locale decimal separator as a plain decimal', () => {
+    const length = { kind: 'length', unitId: 'm' } as const
+
+    expect(measurementHint('1,000', length, { locale: 'en' })).not.toBeNull()
+    expect(measurementHint('-1,000', length, { locale: 'en' })).not.toBeNull()
+    expect(measurementHint('1,5', length, { locale: 'en' })).not.toBeNull()
+
+    expect(measurementHint('1,5', length, { locale: 'fr' })).toBeNull()
+    expect(parseMeasurement('2,75 m', length, { locale: 'fr' })).toBe(2.75)
+  })
 })

package/src/lib/measurements.ts

@@ -1,4 +1,4 @@
-import type { MeasurementPoint } from '@pascal-app/core'
+import { formatNumber, type MeasurementPoint, parseLocalizedNumber } from '@pascal-app/core'
 
 export type LinearUnit = 'metric' | 'imperial'
 export type MetricNotation = 'meters' | 'millimeters'
@@ -119,6 +119,15 @@ export function linearUnitToMeters(value: number, unit: LinearUnit): number {
   return unit === 'imperial' ? value * METERS_PER_FOOT : value
 }
 
+export function parseLinearMeasurementInput(
+  value: string,
+  unit: LinearUnit,
+  locale: string,
+): number | null {
+  const parsed = parseLocalizedNumber(value, locale)
+  return parsed === null ? null : linearUnitToMeters(parsed, unit)
+}
+
 export function linearControlValueToMeters(
   value: number,
   unit: LinearUnit,
@@ -153,7 +162,10 @@ export function formatAreaLabel(
 ): string {
   if (!Number.isFinite(squareMeters)) return '--'
 
-  return `${squareMetersToAreaUnit(squareMeters, unit).toFixed(fractionDigits)}${getAreaUnitLabel(unit)}`
+  return `${formatNumber(squareMetersToAreaUnit(squareMeters, unit), {
+    min: fractionDigits,
+    max: fractionDigits,
+  })}${getAreaUnitLabel(unit)}`
 }
 
 export function cubicMetersToVolumeUnit(cubicMeters: number, unit: LinearUnit): number {
@@ -171,7 +183,10 @@ export function formatVolumeLabel(
 ): string {
   if (!Number.isFinite(cubicMeters)) return '--'
 
-  return `${cubicMetersToVolumeUnit(cubicMeters, unit).toFixed(fractionDigits)}${getVolumeUnitLabel(unit)}`
+  return `${formatNumber(cubicMetersToVolumeUnit(cubicMeters, unit), {
+    min: fractionDigits,
+    max: fractionDigits,
+  })}${getVolumeUnitLabel(unit)}`
 }
 
 export function formatLinearMeasurement(
@@ -200,11 +215,11 @@ export function formatLinearMeasurement(
   if (metricNotation === 'millimeters') {
     const roundedMillimeters = Math.round(absoluteMeters * 1000)
     const sign = meters < 0 && roundedMillimeters !== 0 ? '-' : ''
-    return `${sign}${roundedMillimeters}mm`
+    return `${sign}${formatNumber(roundedMillimeters, { max: 0 })}mm`
   }
 
   const roundedMeters = Number.parseFloat(absoluteMeters.toFixed(2))
   const sign = meters < 0 && roundedMeters !== 0 ? '-' : ''
 
-  return `${sign}${roundedMeters}m`
+  return `${sign}${formatNumber(roundedMeters, { max: 2 })}m`
 }

package/src/lib/mezzanine-selection.test.ts

@@ -169,7 +169,9 @@ describe('mezzanine selection', () => {
     expect(gesture(hostId, ROOM_MOVE_DRAG_LABEL)).toBeNull()
     expect(gesture(mezzanineId, 'height')).toBeNull()
     expect(mezzanineGesture(null, nodes())).toBeNull()
-    expect(MEZZANINE_GESTURE_HINTS.move[0]!.label).toBe('Place inside the room')
+    expect(MEZZANINE_GESTURE_HINTS.move[0]!.label).toMatchObject({
+      message: 'Place inside the room',
+    })
   })
 
   test('the delete dialog speaks of the mezzanine, and of its items only when it has some', () => {

package/src/lib/orbit-near-plane.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'bun:test'
+import { CLOSE_UP_NEAR, ORBIT_NEAR, orbitNearPlane } from './orbit-near-plane'
+
+describe('the orbit near plane follows the eye in', () => {
+  test("standing back it is the viewer's own; close in, a tenth of the distance; never under an inch-off look", () => {
+    expect(orbitNearPlane(40)).toBe(ORBIT_NEAR)
+    expect(orbitNearPlane(3)).toBe(ORBIT_NEAR)
+    expect(orbitNearPlane(1)).toBeCloseTo(0.1, 9)
+    expect(orbitNearPlane(0.5)).toBeCloseTo(0.05, 9)
+    expect(orbitNearPlane(0.01)).toBe(CLOSE_UP_NEAR)
+  })
+})

package/src/lib/orbit-near-plane.ts

@@ -0,0 +1,13 @@
+/** The viewer's near plane (`viewerCameraClipping`), kept while the eye stands back. */
+export const ORBIT_NEAR = 0.3
+/** How close the near plane comes in when the eye does: a casing seen from an inch off. */
+export const CLOSE_UP_NEAR = 0.01
+
+/**
+ * The near plane for an orbit `distance` from its target: a tenth of it, between `CLOSE_UP_NEAR`
+ * and the viewer's own, so zooming in on a window's trim never clips it while the eye standing
+ * back keeps the depth precision it had.
+ */
+export function orbitNearPlane(distance: number): number {
+  return Math.min(ORBIT_NEAR, Math.max(CLOSE_UP_NEAR, distance * 0.1))
+}

package/src/lib/paint-regions.test.ts

@@ -136,10 +136,11 @@ describe('paint region sub-mode', () => {
   })
 
   test('off anything it draws on, the HUD says where to go: a floor for Polygon', () => {
-    expect(paintRegionHints('polygon', null, false).map((hint) => hint.label)).toEqual([
-      'Hover a floor or ceiling',
-      'Cancel',
-    ])
+    expect(
+      paintRegionHints('polygon', null, false).map((hint) =>
+        typeof hint.label === 'string' ? hint.label : hint.label.message,
+      ),
+    ).toEqual(['Hover a floor or ceiling', 'Cancel'])
     expect(paintRegionHints('rectangle', null, false)[0]).toMatchObject({
       label: 'Hover a wall, floor or ceiling',
       active: true,
@@ -158,7 +159,9 @@ describe('paint region sub-mode', () => {
 
 test('the whole-surface HUD says what a click does; only painting teaches the held eyedropper', () => {
   const labels = (mode: Parameters<typeof paintHints>[0]) =>
-    paintHints(mode).map((hint) => hint.label)
+    paintHints(mode).map((hint) =>
+      typeof hint.label === 'string' ? hint.label : (hint.label.message ?? ''),
+    )
   expect(labels('surface')).toEqual(['Hold to pick a material'])
   expect(labels('erase')).toEqual(['Remove a painted part, or reset a surface'])
   expect(labels('erase').some((label) => /pick|colour|color|paint with/i.test(label))).toBe(false)

package/src/lib/paint-scope.test.ts

@@ -790,3 +790,56 @@ describe('generated floor plates: scopes per surface', () => {
     expect(paintScopeRole(manual, 'surface', 'room')).toBe('surface')
   })
 })
+
+describe('a surface that declares its own scopes', () => {
+  it('offers its scopes and labels and paints the role it names for the scope', () => {
+    const kind = 'paint-surface-scope-test'
+    if (!nodeRegistry.has(kind))
+      registerNode({
+        kind,
+        schemaVersion: 1,
+        schema: z.object({ type: z.literal(kind) }) as never,
+        category: 'structure',
+        defaults: () => ({}),
+        capabilities: {
+          slots: () => [{ slotId: 'end:1', label: 'End' }],
+          paint: {
+            resolveRole: () => null,
+            buildPatch: () => ({}),
+            applyPreview: () => null,
+            roleLabel: (_node: AnyNode, role: string) => (role === 'end:1' ? 'This end' : null),
+            scopes: (_node: AnyNode, role: string) =>
+              role === 'end:1'
+                ? {
+                    scopes: ['single', 'matching'],
+                    labels: { matching: 'Every end' },
+                    roleFor: (scope: PaintScope) => (scope === 'matching' ? 'ends:all' : role),
+                  }
+                : null,
+          },
+        },
+        floorplanScope: 'level',
+        renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+      } as unknown as AnyNodeDefinition)
+    const node = { id: 'scoped_1', type: kind } as unknown as AnyNode
+    const hover = paintHoverInfo(node, 'end:1', [])
+    expect(hover.scopes).toEqual(['single', 'matching'])
+    expect(paintScopeLabel('single', hover)).toBe('This end')
+    expect(paintScopeLabel('matching', hover)).toBe('Every end')
+    const targets = (scope: PaintScope) =>
+      resolvePaintScopeTargets({
+        node,
+        role: 'end:1',
+        scope,
+        nodes: { scoped_1: node },
+        spaces: {},
+        slotRolesOf: () => [],
+      }).map((target) => `${target.nodeId}:${target.role}`)
+    expect(targets('single')).toEqual(['scoped_1:end:1'])
+    expect(targets('matching')).toEqual(['scoped_1:ends:all'])
+    // a scope the surface does not offer paints the surface alone
+    expect(targets('room')).toEqual(['scoped_1:end:1'])
+    // other roles of the kind keep the derived set
+    expect(availablePaintScopes({ node, slotRoles: [], role: 'side' })).toEqual(['single'])
+  })
+})

package/src/lib/paint-scope.ts

@@ -55,6 +55,11 @@ function nodeOffersRoomScope(node: AnyNode): boolean {
   return nodeRegistry.get(node.type)?.capabilities?.paint?.roomScope === true
 }
 
+/** The scopes the hovered surface declares for itself (`capabilities.paint.scopes`), if any. */
+function surfaceScopes(node: AnyNode, role: string) {
+  return nodeRegistry.get(node.type)?.capabilities?.paint?.scopes?.(node, role) ?? null
+}
+
 const isFloorPlate = (node: AnyNode): boolean => node.type === 'slab' && node.boundary === 'auto'
 
 const FOOTPRINT_FACE_LABELS: Record<string, string> = {
@@ -104,6 +109,8 @@ export function availablePaintScopes(args: {
   if (args.node.type === 'wall') return ['single', 'room']
   const plate = args.role === undefined ? null : platePaintScopes(args.node, args.role)
   if (plate) return plate.scopes
+  const own = args.role === undefined ? null : surfaceScopes(args.node, args.role)
+  if (own) return own.scopes
   const scopes: PaintScope[] = ['single']
   if (args.slotRoles.length > 1) scopes.push('object')
   if (nodeHasAsset(args.node)) scopes.push('matching')
@@ -123,7 +130,7 @@ export function paintHoverInfo(node: AnyNode, role: string, slotRoles: string[])
     scopes: availablePaintScopes({ node, slotRoles, role }),
     slotLabel: paintSurfaceLabel(node, role),
     nodeNoun: node.type,
-    labels: platePaintScopes(node, role)?.labels,
+    labels: platePaintScopes(node, role)?.labels ?? surfaceScopes(node, role)?.labels,
   }
 }
 
@@ -168,12 +175,13 @@ export function paintSurfaceLabel(node: AnyNode, role: string): string {
   return slotDisplayLabel(node, role)
 }
 
-/** Display label for the hovered slot — declared label wins, else derived from the id. */
+/** Display label for the hovered slot, with a capability override for contextual copy. */
 export function slotDisplayLabel(node: AnyNode, role: string): string {
   const capabilities = nodeRegistry.get(node.type)?.capabilities
+  const roleLabel = capabilities?.paint?.roleLabel?.(node, role)
+  if (roleLabel) return roleLabel
   const declared = capabilities?.slots?.(node)?.find((slot) => slot.slotId === role)
-  if (declared) return declared.label
-  return capabilities?.paint?.roleLabel?.(node, role) ?? slotLabelFromId(role)
+  return declared?.label ?? slotLabelFromId(role)
 }
 
 // ── Fan-out resolution ──────────────────────────────────────────────────────
@@ -506,6 +514,12 @@ export function resolvePaintScopeTargets(args: {
       .map((other) => ({ nodeId: other.id, role: stepRole }))
     return targets.length ? targets : [{ nodeId: node.id as AnyNodeId, role: stepRole }]
   }
+  // A surface with its own scope set paints the role it names for the scope.
+  const own = surfaceScopes(node, role)
+  if (own) {
+    const roleFor = own.roleFor?.(effectivePaintScope(scope, own.scopes)) ?? role
+    return [{ nodeId: node.id as AnyNodeId, role: roleFor }]
+  }
   if (scope === 'single') return single
 
   // Whole object: paint every slot of the clicked node. Generic across any

package/src/lib/panel-rows.ts

@@ -65,19 +65,28 @@ export const PANEL_MODEL_EXTENSION = 'pascal:editor/panel-model'
 /**
  * A control the multi-selection inspector renders for every selected node of
  * a kind at once (derived settings the raw parametrics can't express). `value`
- * null means the selection is mixed: no option shows as active.
+ * null means the selection is mixed: no option shows as active. `segmented`
+ * suits a few short options, `select` a longer list; `readout` only shows a
+ * value the selection cannot edit here.
  */
 export type MultiPanelControl = {
   id: string
-  kind: 'segmented'
-  /** The parametrics group title the control sits in. */
+  /**
+   * The section the control sits in: a parametrics group title, or a section
+   * of its own, shown after the groups in the order controls name them.
+   */
   section: string
   label: string
-  options: ReadonlyArray<{ value: string; label: string }>
-  value: string | null
-  /** Applies to every selected node in one undo step. */
-  onChange: (value: string) => void
-}
+} & (
+  | {
+      kind: 'segmented' | 'select'
+      options: ReadonlyArray<{ value: string; label: string }>
+      value: string | null
+      /** Applies to every selected node in one undo step. */
+      onChange: (value: string) => void
+    }
+  | { kind: 'readout'; value: string; detail?: string }
+)
 
 export type NodePanelModel<N extends AnyNode = AnyNode> = {
   rows: (context: {

package/src/lib/reference-scale.ts

@@ -0,0 +1,83 @@
+import { formatNumber, type GuideScaleReference } from '@pascal-app/core'
+
+export type ReferenceScaleUnit = 'meters' | 'centimeters' | 'feet' | 'inches'
+
+const MAX_REFERENCE_SCALE_LABEL_LENGTH = 64
+
+/** Mirrors `GuideScaleReference.displayLength`'s `.max()` in core. */
+export const MAX_REFERENCE_SCALE_DISPLAY_LENGTH = 1_000_000
+
+export function isValidReferenceScaleDisplayLength(value: number): boolean {
+  return Number.isFinite(value) && value > 0 && value <= MAX_REFERENCE_SCALE_DISPLAY_LENGTH
+}
+
+const REFERENCE_SCALE_UNIT_LABELS: Record<ReferenceScaleUnit, string> = {
+  meters: 'm',
+  centimeters: 'cm',
+  feet: 'ft',
+  inches: 'in',
+}
+
+function formatScaleValue(value: number, unit: string, locale: string): string {
+  return `${formatNumber(value, { locale, max: 2 })} ${unit}`
+}
+
+function getReferenceScaleUnitLabel(unit: unknown): string | null {
+  if (typeof unit !== 'string' || !Object.hasOwn(REFERENCE_SCALE_UNIT_LABELS, unit)) return null
+  return REFERENCE_SCALE_UNIT_LABELS[unit as ReferenceScaleUnit]
+}
+
+function parseLegacyScaleLabel(label: string): { unit: string; value: number } | null {
+  // `\s` covers NBSP and narrow NBSP; the whitespace run and digit group are
+  // disjoint, so each repetition has exactly one way to match.
+  const match = label.trim().match(/^([+−-]?[\d.,]+(?:\s+[\d.,]+)*)\s*(m|cm|ft|in)$/i)
+  if (!match) return null
+
+  const compact = match[1]!.replace(/\s/g, '').replace('−', '-')
+  const lastDot = compact.lastIndexOf('.')
+  const lastComma = compact.lastIndexOf(',')
+  const separatorIndex = Math.max(lastDot, lastComma)
+  const trailingDigits = separatorIndex === -1 ? 0 : compact.length - separatorIndex - 1
+  const decimalSeparator =
+    separatorIndex !== -1 && trailingDigits > 0 && trailingDigits <= 2
+      ? compact[separatorIndex]
+      : null
+  const normalized = decimalSeparator
+    ? `${compact.slice(0, separatorIndex).replace(/[.,]/g, '')}.${compact
+        .slice(separatorIndex + 1)
+        .replace(/[.,]/g, '')}`
+    : compact.replace(/[.,]/g, '')
+
+  if (!/^[+-]?\d+(?:\.\d+)?$/.test(normalized)) return null
+  const value = Number(normalized)
+  return Number.isFinite(value) ? { unit: match[2]!.toLowerCase(), value } : null
+}
+
+export function createGuideScaleReference(
+  reference: Omit<GuideScaleReference, 'displayLength' | 'displayUnit' | 'label'>,
+  displayLength: number,
+  displayUnit: ReferenceScaleUnit,
+): GuideScaleReference {
+  const unitLabel = REFERENCE_SCALE_UNIT_LABELS[displayUnit]
+  const label = formatScaleValue(displayLength, unitLabel, 'en')
+  if (!isValidReferenceScaleDisplayLength(displayLength)) return { ...reference, label }
+  return { ...reference, displayLength, displayUnit, label }
+}
+
+export function formatReferenceScaleLabel(reference: GuideScaleReference, locale: string): string {
+  const unitLabel = getReferenceScaleUnitLabel(reference.displayUnit)
+  if (
+    typeof reference.displayLength === 'number' &&
+    Number.isFinite(reference.displayLength) &&
+    unitLabel
+  ) {
+    return formatScaleValue(reference.displayLength, unitLabel, locale)
+  }
+
+  const label: unknown = reference.label
+  if (typeof label !== 'string') return typeof label === 'number' ? String(label) : ''
+  if (label.length > MAX_REFERENCE_SCALE_LABEL_LENGTH) return label
+
+  const parsed = parseLegacyScaleLabel(label)
+  return parsed ? formatScaleValue(parsed.value, parsed.unit, locale) : label
+}