@pascal-app/editor 0.8.0 → 0.9.2

package/src/lib/material-paint.ts

@@ -1,29 +1,54 @@
 'use client'
 
 import {
+  type AnyNode,
+  type AnyNodeId,
   type CeilingNode,
+  type ChimneyMaterialRole,
+  type ChimneyNode,
   type ColumnNode,
+  type DormerSurfaceMaterialRole,
   type FenceNode,
   getCatalogMaterialById,
   getEffectiveRoofSurfaceMaterial,
+  getEffectiveSegmentSurfaceMaterial,
   getEffectiveStairSurfaceMaterial,
-  getEffectiveWallSurfaceMaterial,
   getLibraryMaterialIdFromRef,
   type MaterialSchema,
   type MaterialTarget,
+  nodeRegistry,
   type RoofNode,
+  type RoofSegmentNode,
+  type RoofSegmentSurfaceMaterialRole,
   type RoofSurfaceMaterialRole,
+  type ShelfNode,
   type SlabNode,
   type StairNode,
   type StairSurfaceMaterialRole,
-  type WallNode,
   type WallSurfaceSide,
 } from '@pascal-app/core'
 
-export type PaintableMaterialTarget = Extract<
-  MaterialTarget,
-  'wall' | 'roof' | 'stair' | 'fence' | 'column' | 'slab' | 'ceiling'
->
+export type PaintableMaterialTarget =
+  | Extract<
+      MaterialTarget,
+      | 'wall'
+      | 'roof'
+      | 'stair'
+      | 'fence'
+      | 'column'
+      | 'slab'
+      | 'ceiling'
+      | 'shelf'
+      | 'cabinet'
+      | 'chimney'
+      | 'dormer'
+      | 'box-vent'
+      | 'ridge-vent'
+      | 'turbine-vent'
+      | 'cupola'
+      | 'eyebrow-vent'
+    >
+  | 'item'
 
 export type SingleSurfaceMaterialRole = 'surface'
 
@@ -52,45 +77,51 @@ export function getActivePaintMaterialLabel(material: ActivePaintMaterial | null
   return getCatalogEntryForActivePaintMaterial(material)?.label ?? 'Custom'
 }
 
-export function buildWallSurfaceMaterialPatch(
-  node: WallNode,
-  targetSide: WallSurfaceSide,
+export function buildRoofSurfaceMaterialPatch(
+  node: RoofNode,
+  targetRole: RoofSurfaceMaterialRole,
   material: MaterialSchema | undefined,
   materialPreset: string | undefined,
-): Partial<WallNode> {
+): Partial<RoofNode> {
   const nextSurfaceMaterial = { material, materialPreset }
-  const nextInterior =
-    targetSide === 'interior'
-      ? nextSurfaceMaterial
-      : getEffectiveWallSurfaceMaterial(node, 'interior')
-  const nextExterior =
-    targetSide === 'exterior'
-      ? nextSurfaceMaterial
-      : getEffectiveWallSurfaceMaterial(node, 'exterior')
+  const nextTop =
+    targetRole === 'top' ? nextSurfaceMaterial : getEffectiveRoofSurfaceMaterial(node, 'top')
+  const nextEdge =
+    targetRole === 'edge' ? nextSurfaceMaterial : getEffectiveRoofSurfaceMaterial(node, 'edge')
+  const nextWall =
+    targetRole === 'wall' ? nextSurfaceMaterial : getEffectiveRoofSurfaceMaterial(node, 'wall')
 
   return {
-    interiorMaterial: nextInterior.material,
-    interiorMaterialPreset: nextInterior.materialPreset,
-    exteriorMaterial: nextExterior.material,
-    exteriorMaterialPreset: nextExterior.materialPreset,
+    topMaterial: nextTop.material,
+    topMaterialPreset: nextTop.materialPreset,
+    edgeMaterial: nextEdge.material,
+    edgeMaterialPreset: nextEdge.materialPreset,
+    wallMaterial: nextWall.material,
+    wallMaterialPreset: nextWall.materialPreset,
     material: undefined,
     materialPreset: undefined,
   }
 }
 
-export function buildRoofSurfaceMaterialPatch(
-  node: RoofNode,
-  targetRole: RoofSurfaceMaterialRole,
+/**
+ * Build a per-segment paint patch for one of the three surface roles. The
+ * segment ends up with role-specific fields set (and the legacy catch-all
+ * `material` cleared) so subsequent reads pick the role override over any
+ * parent-roof fallback.
+ */
+export function buildRoofSegmentSurfaceMaterialPatch(
+  node: RoofSegmentNode,
+  targetRole: RoofSegmentSurfaceMaterialRole,
   material: MaterialSchema | undefined,
   materialPreset: string | undefined,
-): Partial<RoofNode> {
+): Partial<RoofSegmentNode> {
   const nextSurfaceMaterial = { material, materialPreset }
   const nextTop =
-    targetRole === 'top' ? nextSurfaceMaterial : getEffectiveRoofSurfaceMaterial(node, 'top')
+    targetRole === 'top' ? nextSurfaceMaterial : getEffectiveSegmentSurfaceMaterial(node, 'top')
   const nextEdge =
-    targetRole === 'edge' ? nextSurfaceMaterial : getEffectiveRoofSurfaceMaterial(node, 'edge')
+    targetRole === 'edge' ? nextSurfaceMaterial : getEffectiveSegmentSurfaceMaterial(node, 'edge')
   const nextWall =
-    targetRole === 'wall' ? nextSurfaceMaterial : getEffectiveRoofSurfaceMaterial(node, 'wall')
+    targetRole === 'wall' ? nextSurfaceMaterial : getEffectiveSegmentSurfaceMaterial(node, 'wall')
 
   return {
     topMaterial: nextTop.material,
@@ -104,6 +135,51 @@ export function buildRoofSurfaceMaterialPatch(
   }
 }
 
+/**
+ * Clear every painted material on a node back to its default. Works for any
+ * kind without per-type knowledge: it nulls the catch-all `material` /
+ * `materialPreset` plus any role field (`*Material` / `*MaterialPreset`) that
+ * the node actually carries. For a roof it also resets every child segment, so
+ * a single call defaults the whole roof system. `updateNode` merges patches
+ * shallowly without re-validation, so the `undefined` values land as cleared
+ * fields and the renderer falls back to the theme defaults.
+ */
+export function buildResetSurfaceMaterialUpdates(
+  nodes: Record<string, AnyNode>,
+  node: AnyNode,
+): { id: AnyNodeId; data: Partial<AnyNode> }[] {
+  const clearPatch = (target: AnyNode): Partial<AnyNode> => {
+    const patch: Record<string, undefined> = {}
+    for (const key of Object.keys(target)) {
+      if (
+        key === 'material' ||
+        key === 'materialPreset' ||
+        key === 'slots' ||
+        key.endsWith('Material') ||
+        key.endsWith('MaterialPreset')
+      ) {
+        patch[key] = undefined
+      }
+    }
+    return patch as Partial<AnyNode>
+  }
+
+  const updates: { id: AnyNodeId; data: Partial<AnyNode> }[] = [
+    { id: node.id as AnyNodeId, data: clearPatch(node) },
+  ]
+
+  if (node.type === 'roof') {
+    for (const segmentId of (node as RoofNode).children ?? []) {
+      const segment = nodes[segmentId as AnyNodeId]
+      if (segment?.type === 'roof-segment') {
+        updates.push({ id: segment.id as AnyNodeId, data: clearPatch(segment) })
+      }
+    }
+  }
+
+  return updates
+}
+
 export function buildStairSurfaceMaterialPatch(
   node: StairNode,
   targetRole: StairSurfaceMaterialRole,
@@ -133,7 +209,7 @@ export function buildStairSurfaceMaterialPatch(
 }
 
 export function buildSingleSurfaceMaterialPatch<
-  TNode extends FenceNode | ColumnNode | SlabNode | CeilingNode,
+  TNode extends FenceNode | ColumnNode | SlabNode | CeilingNode | ShelfNode,
 >(material: MaterialSchema | undefined, materialPreset: string | undefined): Partial<TNode> {
   return {
     material,
@@ -141,6 +217,29 @@ export function buildSingleSurfaceMaterialPatch<
   } as Partial<TNode>
 }
 
+// Chimney / dormer patch builders moved to
+// `@pascal-app/nodes/<kind>/paint.ts` and are wired into the kind's
+// `capabilities.paint.buildPatch`. The selection-manager invokes them
+// through the registry; no editor-side helper needed here.
+//
+// `getEffectiveChimneyMaterial` below stays because
+// `resolveActivePaintMaterialFromSelection` (also in this file) still
+// has wall / roof / stair arms that follow the same shape — they all
+// migrate together in a follow-up.
+
+export function getEffectiveChimneyMaterial(
+  node: ChimneyNode,
+  role: ChimneyMaterialRole,
+): { material: MaterialSchema | undefined; materialPreset: string | undefined } {
+  if (role === 'top') {
+    const hasTop = node.topMaterial !== undefined || node.topMaterialPreset !== undefined
+    if (hasTop) {
+      return { material: node.topMaterial, materialPreset: node.topMaterialPreset }
+    }
+  }
+  return { material: node.material, materialPreset: node.materialPreset }
+}
+
 export function resolveActivePaintMaterialFromSelection(params: {
   nodes: Record<string, any>
   selectedId: string | null
@@ -150,7 +249,10 @@ export function resolveActivePaintMaterialFromSelection(params: {
       | WallSurfaceSide
       | StairSurfaceMaterialRole
       | RoofSurfaceMaterialRole
+      | ChimneyMaterialRole
+      | DormerSurfaceMaterialRole
       | SingleSurfaceMaterialRole
+      | string
   } | null
 }): ActivePaintMaterial | null {
   const { nodes, selectedId, selectedMaterialTarget } = params
@@ -160,22 +262,31 @@ export function resolveActivePaintMaterialFromSelection(params: {
   const selectedNode = nodes[selectedId]
   if (!selectedNode) return null
 
-  if (
-    selectedNode.type === 'wall' &&
-    (selectedMaterialTarget.role === 'interior' || selectedMaterialTarget.role === 'exterior')
-  ) {
-    const surface = getEffectiveWallSurfaceMaterial(selectedNode, selectedMaterialTarget.role)
-    return hasActivePaintMaterial({
-      material: surface.material,
-      materialPreset: surface.materialPreset,
-      sourceTarget: 'wall',
+  // Registry-driven path. Kinds that declare
+  // `capabilities.paint.getEffectiveMaterial` resolve their effective
+  // material here without an editor-side per-kind arm. Wall,
+  // chimney, dormer use this; roof / stair stay legacy below.
+  const paintCap = nodeRegistry.get(selectedNode.type)?.capabilities?.paint
+  if (paintCap?.getEffectiveMaterial) {
+    const surface = paintCap.getEffectiveMaterial({
+      node: selectedNode,
+      role: selectedMaterialTarget.role as string,
+      nodes,
     })
-      ? {
-          material: surface.material,
-          materialPreset: surface.materialPreset,
-          sourceTarget: 'wall',
-        }
-      : null
+    if (surface) {
+      const sourceTarget = (paintCap.materialTarget ?? selectedNode.type) as PaintableMaterialTarget
+      return hasActivePaintMaterial({
+        material: surface.material,
+        materialPreset: surface.materialPreset,
+        sourceTarget,
+      })
+        ? {
+            material: surface.material,
+            materialPreset: surface.materialPreset,
+            sourceTarget,
+          }
+        : null
+    }
   }
 
   if (
@@ -184,7 +295,27 @@ export function resolveActivePaintMaterialFromSelection(params: {
       selectedMaterialTarget.role === 'edge' ||
       selectedMaterialTarget.role === 'wall')
   ) {
-    const surface = getEffectiveRoofSurfaceMaterial(selectedNode, selectedMaterialTarget.role)
+    let surface = getEffectiveRoofSurfaceMaterial(selectedNode, selectedMaterialTarget.role)
+    if (
+      selectedMaterialTarget.role === 'top' &&
+      surface.material === undefined &&
+      surface.materialPreset === undefined
+    ) {
+      const roofNode = selectedNode as RoofNode
+      const fallbackSegment = (roofNode.children ?? [])
+        .map((id: AnyNodeId) => nodes[id as AnyNodeId] as RoofSegmentNode | undefined)
+        .find(
+          (segment: RoofSegmentNode | undefined) =>
+            segment?.type === 'roof-segment' &&
+            (segment.material !== undefined || segment.materialPreset !== undefined),
+        )
+      if (fallbackSegment) {
+        surface = {
+          material: fallbackSegment.material,
+          materialPreset: fallbackSegment.materialPreset,
+        }
+      }
+    }
     return hasActivePaintMaterial({
       material: surface.material,
       materialPreset: surface.materialPreset,
@@ -218,13 +349,21 @@ export function resolveActivePaintMaterialFromSelection(params: {
       : null
   }
 
+  // Wall / chimney / dormer flow through the registry-driven path
+  // at the top of this function.
+
+  // Slot-backed kinds resolve via the registry-driven `getEffectiveMaterial`
+  // path at the top of this function, including legacy inline-material
+  // fallbacks when their capability exposes one.
+
   if (
     (selectedNode.type === 'fence' ||
       selectedNode.type === 'column' ||
-      selectedNode.type === 'slab' ||
-      selectedNode.type === 'ceiling') &&
+      selectedNode.type === 'shelf') &&
     selectedMaterialTarget.role === 'surface'
   ) {
+    // Roof vents previously lived here too; they now resolve via the
+    // registry-driven `getEffectiveMaterial` path at the top of this function.
     const target = selectedNode.type
     return hasActivePaintMaterial({
       material: selectedNode.material,
@@ -252,6 +391,10 @@ export function resolvePaintTargetFromSelection(params: {
   const selectedNode = nodes[selectedId]
   if (!selectedNode) return null
 
+  const registryPaintTarget = nodeRegistry.get(selectedNode.type)?.capabilities?.paint
+    ?.materialTarget
+  if (registryPaintTarget) return registryPaintTarget as PaintableMaterialTarget
+
   if (selectedNode.type === 'wall') {
     return 'wall'
   }
@@ -280,5 +423,41 @@ export function resolvePaintTargetFromSelection(params: {
     return 'ceiling'
   }
 
+  if (selectedNode.type === 'shelf') {
+    return 'shelf'
+  }
+
+  if (selectedNode.type === 'item') {
+    return 'item'
+  }
+
+  if (selectedNode.type === 'chimney') {
+    return 'chimney'
+  }
+
+  if (selectedNode.type === 'dormer') {
+    return 'dormer'
+  }
+
+  if (selectedNode.type === 'box-vent') {
+    return 'box-vent'
+  }
+
+  if (selectedNode.type === 'ridge-vent') {
+    return 'ridge-vent'
+  }
+
+  if (selectedNode.type === 'turbine-vent') {
+    return 'turbine-vent'
+  }
+
+  if (selectedNode.type === 'cupola') {
+    return 'cupola'
+  }
+
+  if (selectedNode.type === 'eyebrow-vent') {
+    return 'eyebrow-vent'
+  }
+
   return null
 }

package/src/lib/measurement-kind.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  CREATABLE_MEASUREMENT_KINDS,
+  DEFAULT_CREATABLE_MEASUREMENT_KIND,
+  normalizeCreatableMeasurementKind,
+} from './measurement-kind'
+
+describe('creatable measurement kinds', () => {
+  test('keeps the supported creation kinds', () => {
+    expect(CREATABLE_MEASUREMENT_KINDS).toEqual([
+      'distance',
+      'angle',
+      'area',
+      'perimeter',
+      'volume',
+    ])
+    for (const kind of CREATABLE_MEASUREMENT_KINDS) {
+      expect(normalizeCreatableMeasurementKind(kind)).toBe(kind)
+    }
+  })
+
+  test.each([
+    'smart',
+    'unknown',
+    null,
+    undefined,
+  ])('falls back from a non-creatable persisted value: %s', (value) => {
+    expect(normalizeCreatableMeasurementKind(value)).toBe(DEFAULT_CREATABLE_MEASUREMENT_KIND)
+  })
+})

package/src/lib/measurement-kind.ts

@@ -0,0 +1,19 @@
+export const CREATABLE_MEASUREMENT_KINDS = [
+  'distance',
+  'angle',
+  'area',
+  'perimeter',
+  'volume',
+] as const
+
+export type CreatableMeasurementKind = (typeof CREATABLE_MEASUREMENT_KINDS)[number]
+
+export const DEFAULT_CREATABLE_MEASUREMENT_KIND: CreatableMeasurementKind = 'distance'
+
+export function isCreatableMeasurementKind(value: unknown): value is CreatableMeasurementKind {
+  return CREATABLE_MEASUREMENT_KINDS.includes(value as CreatableMeasurementKind)
+}
+
+export function normalizeCreatableMeasurementKind(value: unknown): CreatableMeasurementKind {
+  return isCreatableMeasurementKind(value) ? value : DEFAULT_CREATABLE_MEASUREMENT_KIND
+}

package/src/lib/measurement-label.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test'
+import { measurementCentroid, pointInPolygon2D } from '@pascal-app/core'
+import { measurementPolygonLabelAnchor, triangulateMeasurementPolygon } from './measurement-label'
+
+describe('measurementPolygonLabelAnchor', () => {
+  test('keeps a concave polygon label inside its visible fill', () => {
+    const base = [
+      [0, 0, 0],
+      [4, 0, 0],
+      [4, 0, 1],
+      [1, 0, 1],
+      [1, 0, 4],
+      [0, 0, 4],
+    ] as [number, number, number][]
+    const centroid = measurementCentroid(base)
+    const anchor = measurementPolygonLabelAnchor(base)
+
+    expect(centroid).not.toBeNull()
+    expect(
+      pointInPolygon2D(
+        [centroid![0], centroid![2]],
+        base.map(([x, , z]) => [x, z]),
+      ),
+    ).toBe(false)
+    expect(anchor).not.toBeNull()
+    expect(
+      pointInPolygon2D(
+        [anchor![0], anchor![2]],
+        base.map(([x, , z]) => [x, z]),
+      ),
+    ).toBe(true)
+  })
+
+  test('returns an on-plane anchor for a sloped polygon', () => {
+    const base = [
+      [0, 0, 0],
+      [4, 2, 0],
+      [4, 2, 4],
+      [0, 0, 4],
+    ] as [number, number, number][]
+    const anchor = measurementPolygonLabelAnchor(base)
+
+    expect(triangulateMeasurementPolygon(base)).toHaveLength(2)
+    expect(anchor).not.toBeNull()
+    expect(anchor![1]).toBeCloseTo(anchor![0] / 2)
+  })
+})

package/src/lib/measurement-label.ts

@@ -0,0 +1,68 @@
+import { type MeasurementPoint, measurementCentroid, measurementNormal } from '@pascal-app/core'
+import { ShapeUtils, Vector2, Vector3 } from 'three'
+
+type MeasurementPolygonProjection = {
+  contour: Vector2[]
+  triangles: number[][]
+}
+
+function projectMeasurementPolygon(
+  points: readonly MeasurementPoint[],
+): MeasurementPolygonProjection | null {
+  const normalValue = measurementNormal(points)
+  const originValue = points[0]
+  if (!(normalValue && originValue)) return null
+
+  const normal = new Vector3(...normalValue)
+  const reference = Math.abs(normal.y) < 0.9 ? new Vector3(0, 1, 0) : new Vector3(1, 0, 0)
+  const tangent = new Vector3().crossVectors(reference, normal).normalize()
+  const bitangent = new Vector3().crossVectors(normal, tangent).normalize()
+  const origin = new Vector3(...originValue)
+  const contour = points.map((point) => {
+    const relative = new Vector3(...point).sub(origin)
+    return new Vector2(relative.dot(tangent), relative.dot(bitangent))
+  })
+
+  return { contour, triangles: ShapeUtils.triangulateShape(contour, []) }
+}
+
+export function triangulateMeasurementPolygon(points: readonly MeasurementPoint[]): number[][] {
+  return projectMeasurementPolygon(points)?.triangles ?? []
+}
+
+export function measurementPolygonLabelAnchor(
+  points: readonly MeasurementPoint[],
+): MeasurementPoint | null {
+  const projection = projectMeasurementPolygon(points)
+  if (!projection || projection.triangles.length === 0) return measurementCentroid(points)
+
+  let largestTriangle: number[] | null = null
+  let largestArea = Number.NEGATIVE_INFINITY
+  for (const triangle of projection.triangles) {
+    const [firstIndex, secondIndex, thirdIndex] = triangle
+    const first = firstIndex === undefined ? null : projection.contour[firstIndex]
+    const second = secondIndex === undefined ? null : projection.contour[secondIndex]
+    const third = thirdIndex === undefined ? null : projection.contour[thirdIndex]
+    if (!(first && second && third)) continue
+    const area = Math.abs(
+      (second.x - first.x) * (third.y - first.y) - (second.y - first.y) * (third.x - first.x),
+    )
+    if (area > largestArea) {
+      largestArea = area
+      largestTriangle = triangle
+    }
+  }
+
+  if (!largestTriangle) return measurementCentroid(points)
+  const [firstIndex, secondIndex, thirdIndex] = largestTriangle
+  const first = firstIndex === undefined ? null : points[firstIndex]
+  const second = secondIndex === undefined ? null : points[secondIndex]
+  const third = thirdIndex === undefined ? null : points[thirdIndex]
+  if (!(first && second && third)) return measurementCentroid(points)
+
+  return [
+    (first[0] + second[0] + third[0]) / 3,
+    (first[1] + second[1] + third[1]) / 3,
+    (first[2] + second[2] + third[2]) / 3,
+  ]
+}

package/src/lib/measurement-parser.ts

@@ -0,0 +1,116 @@
+import { type Kind, parseQuantity, quantity } from '@pascal-app/lingo'
+
+/**
+ * Natural-language measurement parsing for editor property fields, backed by
+ * `@pascal-app/lingo`. Lets a user type `6ft`, `180cm`, `1m80`, `5'11"`, `45°`
+ * or `1.57rad` into any measurement field and have it canonicalized to the
+ * unit the field stores its value in — independent of the metric/imperial
+ * display toggle.
+ *
+ * The editor stores linear values in meters and angular values in radians (a
+ * few fields store inches or degrees); lingo's `length` base is meters and its
+ * `angle` base is radians, so a field's `unit` prop already names the stored /
+ * canonical unit and doubles as the parse target.
+ */
+
+export interface LingoUnitSpec {
+  kind: Kind
+  /** Unit id the field's stored `value` is expressed in — the parse target. */
+  unitId: string
+}
+
+/**
+ * Map an editor field `unit` prop to a lingo kind + canonical unit. Returns
+ * `null` for units we deliberately do NOT natural-language-parse (plain
+ * numbers, percentages, angular rates, counts) so those keep exact
+ * `Number.parseFloat` behavior.
+ */
+export function lingoUnitSpec(unit: string | undefined): LingoUnitSpec | null {
+  switch (unit) {
+    case 'm':
+    case 'cm':
+    case 'mm':
+    case 'in':
+    case 'ft':
+      return { kind: 'length', unitId: unit }
+    case '°':
+    case 'deg':
+    case 'degrees':
+      return { kind: 'angle', unitId: 'deg' }
+    case 'rad':
+    case 'radians':
+      return { kind: 'angle', unitId: 'rad' }
+    default:
+      return null
+  }
+}
+
+export interface ParseMeasurementOptions {
+  /**
+   * Implied unit for a BARE number (e.g. `6` → `6 ft`). Defaults to the field's
+   * own `unitId`. A typed unit (`180cm`) is always honored regardless.
+   */
+  bareUnit?: string
+  /** Disambiguates gal/ton/cup families; harmless for length/angle. */
+  system?: 'metric' | 'us' | 'imperial'
+}
+
+/**
+ * Parse typed field text into the field's stored numeric unit. Returns `null`
+ * when the text can't be read as a quantity, so the caller can fall back to a
+ * plain number parse or revert to the previous value.
+ */
+export function parseMeasurement(
+  raw: string,
+  spec: LingoUnitSpec,
+  options: ParseMeasurementOptions = {},
+): number | null {
+  const result = parseQuantity(raw, {
+    kind: spec.kind,
+    unit: options.bareUnit ?? spec.unitId,
+    system: options.system,
+    strictness: 'forgiving',
+  })
+  if (!result.ok) return null
+  const value = result.quantity.to(spec.unitId).value
+  return Number.isFinite(value) ? value : null
+}
+
+export interface MeasurementHintOptions extends ParseMeasurementOptions {
+  /** Unit id the preview is rendered in (the field's displayed unit). */
+  displayUnit?: string
+  /** Max fraction digits in the preview. */
+  precision?: number
+  /**
+   * Clamp applied to the parsed stored value before previewing, so the hint
+   * reflects what a commit would actually store on a bounded field.
+   */
+  clamp?: (stored: number) => number
+}
+
+const PLAIN_NUMBER = /^[+-]?\d*\.?\d*$/
+
+/**
+ * A faint "= 1.83 m" preview of the value currently being typed, shown only
+ * when the user typed something beyond a plain decimal in the field's own unit
+ * (an explicit unit, a compound like `1m80`, or a number word) and it parses.
+ * Returns `null` when there's nothing useful to preview.
+ */
+export function measurementHint(
+  raw: string,
+  spec: LingoUnitSpec,
+  options: MeasurementHintOptions = {},
+): string | null {
+  const trimmed = raw.trim()
+  if (!trimmed || PLAIN_NUMBER.test(trimmed)) return null
+
+  const parsed = parseMeasurement(trimmed, spec, options)
+  if (parsed === null) return null
+  const stored = options.clamp ? options.clamp(parsed) : parsed
+
+  const displayUnit = options.displayUnit ?? spec.unitId
+  const precision = options.precision ?? 2
+  const q = quantity(stored, spec.unitId)
+  const shown = displayUnit === spec.unitId ? q : q.to(displayUnit)
+  return `= ${shown.format({ precision })}`
+}