@things-factory/figure-ui 10.1.4 → 10.1.6

package/client/modeller/figure-source.test.ts

@@ -149,7 +149,6 @@ const FULL: FigureSource = {
   base: { x: 3000, y: 800, z: 2000 },
   detailLevel: 'L',
   styleKit: 'factory',
-  anchor: { x: 0, y: -400, z: 0 },
   parts: [
     {
       name: 'deck',
@@ -200,8 +199,23 @@ const FULL: FigureSource = {
       material: { token: 'palette.neutral' },
       sizing: 'repeat',
       repeat: { axis: 'x', pitch: 200 }
+    },
+    {
+      /*
+        물건을 놓는 자리이면서 드나드는 문이다 — AGV 의 상판이 그렇다. **그려지지 않으므로**
+        재질이 없다.
+
+        그리지 않는 것이라 화면으로는 왕복에서 누락됐는지 알 수 없다. 자리를 잃어버린 도형은
+        멀쩡해 보이면서 아무것도 받지 못한다.
+      */
+      name: 'seat',
+      primitive: 'cube',
+      transform: { position: { x: 0, y: 420, z: 0 }, size: { x: 700, y: 500, z: 500 } },
+      capability: { roles: ['slot', 'port-in', 'port-out'], accepts: ['PALLET'], capacity: 2 }
     }
   ],
+  /* 이 도형이 지는 능력. 부품이 아니라 도형 전체의 것이다. */
+  capabilities: ['FlowNode'],
   /*
     움직임. 편집면이 아직 안 만지는 자리이며, **바로 그래서 여기 있다.**
 

package/client/modeller/figure-source.ts

@@ -82,14 +82,6 @@ export interface BoardModel {
   figureType?: string
   detailLevel?: DetailLevel
   styleKit?: string
-  /**
-   * 형상 전체의 기준점.
-   *
-   * **부품의 `anchor` 와 다른 것이다.** 이쪽은 점(`Vec3`)이고 저쪽은 축별로 어느 면을
-   * 붙잡느냐다. 한 형식 안에 같은 낱말이 둘인 것은 좋지 않으나, 이름을 바꾸면 저장된
-   * 원본이 따라와야 하므로 여기서 정하지 않는다.
-   */
-  anchor?: Vec3
   /**
    * 움직임. **부품 바깥에 있다** — clip 하나가 부품 여럿을 함께 움직이기 때문이다.
    *
@@ -97,6 +89,14 @@ export interface BoardModel {
    * 저장하는 것만으로 **조용히 지워지기** 때문이다.
    */
   animations?: FigureSource['animations']
+  /**
+   * 이 도형이 지는 능력. 씬의 capability mixin 이름이다.
+   *
+   * **부품이 아니라 도형 전체의 것이다** — 「이 컨베이어는 흐름의 마디다」는 부품 하나가
+   * 아니라 도형이 지는 성질이다. 부품 쪽 `capability` 는 그 능력을 **어느 부품이 받쳐
+   * 주나**를 말하는 다른 칸이다.
+   */
+  capabilities?: FigureSource['capabilities']
 }
 
 /** 부품 컴포넌트의 상태. 씬의 용어 그대로다. */
@@ -159,6 +159,13 @@ export interface PartModel {
   anchor?: FigurePart['anchor']
   repeat?: FigurePart['repeat']
   label?: FigurePart['label']
+  /**
+   * 이 부품이 능력의 어느 자리인가 — 물건이 앉는 자리(slot)이거나 드나드는 문(port)이다.
+   *
+   * 이 칸이 있는 부품은 **그려지지 않는다.** 저작면에서는 어디인지 보여야 하니 그리지만,
+   * 청사진에서는 `groups` 가 아니라 `anchors` 로 간다.
+   */
+  capability?: FigurePart['capability']
 }
 
 const RAD_TO_DEG = 180 / Math.PI
@@ -223,11 +230,11 @@ export function toFigureSource(board: BoardModel, parts: PartModel[]): FigureSou
   return withoutEmpty({
     type: board.figureType ?? '',
     base: { x: board.width, y: board.depth, z: board.height },
-    anchor: board.anchor,
     detailLevel: board.detailLevel,
     styleKit: board.styleKit,
     parts: parts.map(part => partTo(part, half)),
-    animations: board.animations
+    animations: board.animations,
+    capabilities: board.capabilities
   }) as FigureSource
 }
 
@@ -239,6 +246,13 @@ function partTo(part: PartModel, half: Vec3): FigurePart {
   })
 
   const shape = withoutEmpty({ round: part.round, path: part.path, hollow: part.hollow })
+  /*
+    재질이 하나도 없으면 **칸 자체를 안 적는다.**
+
+    빈 객체를 적으면 형식이 「재질은 있는데 무엇으로 칠할지 모른다」로 읽어
+    `material-unresolvable` 을 낸다. 그리지 않는 자리(`capability`)에는 재질이 없는 것이
+    정상이고, 그 부품이 조용히 오류를 달고 다니게 된다.
+  */
   const material = withoutEmpty({
     token: part.token,
     preset: part.preset,
@@ -262,13 +276,14 @@ function partTo(part: PartModel, half: Vec3): FigurePart {
     }),
     segments: part.segments,
     shape: Object.keys(shape).length > 0 ? shape : undefined,
-    material,
+    material: Object.keys(material).length > 0 ? material : undefined,
     materialSlot: part.materialSlot,
     keepRound: part.keepRound,
     sizing: part.sizing,
     anchor: part.anchor,
     repeat: part.repeat,
-    label: part.label
+    label: part.label,
+    capability: part.capability
   }) as FigurePart
 }
 
@@ -283,8 +298,8 @@ export function fromFigureSource(source: FigureSource): { board: BoardModel; par
     figureType: source.type,
     detailLevel: source.detailLevel,
     styleKit: source.styleKit,
-    anchor: source.anchor,
-    animations: source.animations
+    animations: source.animations,
+    capabilities: source.capabilities
   }) as BoardModel
 
   return { board, parts: source.parts.map(part => partFrom(part, half)) }
@@ -333,6 +348,7 @@ function partFrom(part: FigurePart, half: Vec3): PartModel {
     sizing: part.sizing,
     anchor: part.anchor,
     repeat: part.repeat,
-    label: part.label
+    label: part.label,
+    capability: part.capability
   }) as PartModel
 }

package/client/modeller/figure-thumbnail.ts

@@ -34,11 +34,40 @@ interface Shooter extends HTMLElement {
   snapshot?: (width?: number, height?: number) => Promise<string | undefined>
 }
 
-/** 프레임 두 장 뒤에 한 번 더 쉰다 — 씬이 서고 카메라가 자리를 잡을 틈. 씬에 그 신호가 없다. */
+/**
+ * 씬이 서고 카메라가 자리를 잡을 틈 — 프레임 두 장 뒤에 한 번 더 쉰다. 씬에 그 신호가 없다.
+ *
+ * **rAF 만 기다리면 안 된다.** 탭이 뒤로 가거나 창이 가려지면 브라우저가 rAF 를 멈추고, 그러면
+ * 이 약속이 영원히 안 풀린다. 그 위에 저장이 얹혀 있어서 저장이 통째로 멈췄다 — 단추는 잠긴 채로,
+ * 아무 말도 없이. [확인함] 2026-09-10 포커스 없는 탭에서 `saving: true` 로 고정.
+ *
+ * 그래서 시계와 함께 경주시킨다. 늦게 깨어난 쪽은 버려지고, 화면이 안 그려지는 상황이면 아래
+ * `snapshot` 이 빈 것을 돌려주거나 시간이 다 된다 — 어느 쪽이든 **저장은 계속 간다.**
+ */
 function settle(): Promise<void> {
-  return new Promise(resolve =>
+  const frames = new Promise<void>(resolve =>
     requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(resolve, 150)))
   )
+
+  return Promise.race([frames, delay(600)])
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * 그림을 기다리는 시간의 한도.
+ *
+ * 3D 를 세워 한 장 찍는 데 걸리는 시간은 형상과 기계에 따라 다르지만, 이 한도의 목적은 빠르기가
+ * 아니라 **저장이 멈추지 않는 것**이다. 넘으면 그림 없이 저장한다 — 정본이 그림보다 중하고,
+ * 그림은 다음에 저작면을 열 때 다시 채운다(`figure-modeller-page` 의 fillThumbnail).
+ */
+const PATIENCE = 5000
+
+/** 시간이 다 되면 없는 것으로 답한다. 던지지 않는다 — 그림이 없는 것은 실패가 아니다. */
+function within<T>(work: Promise<T>, ms: number): Promise<T | undefined> {
+  return Promise.race([work, delay(ms).then(() => undefined)])
 }
 
 export async function captureThumbnail(
@@ -66,9 +95,25 @@ export async function captureThumbnail(
 
   try {
     host.appendChild(shooter)
-    await settle()
 
-    return shooter.snapshot ? await shooter.snapshot(WIDTH, HEIGHT) : undefined
+    /*
+      **한도 안에 못 찍으면 그림 없이 간다.** 이 함수를 부르는 자리가 저장이고, 저장은 그림을
+      기다리다 멈춰서는 안 된다. 못 찍은 것은 조용히 넘기지 않고 콘솔에 남긴다 — 그림이 계속
+      안 생기면 그 줄이 단서가 된다.
+    */
+    const shot = await within(
+      (async () => {
+        await settle()
+        return shooter.snapshot ? await shooter.snapshot(WIDTH, HEIGHT) : undefined
+      })(),
+      PATIENCE
+    )
+
+    if (!shot) {
+      console.warn(`[thumbnail] ${PATIENCE}ms 안에 못 찍었습니다 — 그림 없이 저장합니다`)
+    }
+
+    return shot
   } catch (e) {
     console.warn(`[thumbnail] 세우지 못했습니다 — ${(e as Error).message}`)
     return undefined

package/client/modeller/maturity.ts

@@ -70,7 +70,7 @@ export function maturityOf(source: FigureSource, cost: FigureCost, score: Figure
 function scale(cost: FigureCost): MaturityAxis {
   const capacity = capacityFrom(cost.groups, cost.triangles)
   if (!capacity) {
-    return { key: 'scale', blocked: 'text.maturity-blocked-no-parts' }
+    return { key: 'scale', blocked: 'figure.text.maturity-blocked-no-parts' }
   }
 
   return {
@@ -79,7 +79,7 @@ function scale(cost: FigureCost): MaturityAxis {
     // 목표를 넘긴 여유는 다른 축을 고치는 데 쓰는 편이 낫다.
     ratio: Math.min(1, capacity.instances / BOARD_ASSETS),
     reading: String(capacity.instances),
-    because: 'text.maturity-scale-because'
+    because: 'figure.text.maturity-scale-because'
   }
 }
 
@@ -102,8 +102,8 @@ function consistency(source: FigureSource, cost: FigureCost): MaturityAxis {
   return {
     key: 'consistency',
     ratio: (3 - faults) / 3,
-    readingKey: faults === 0 ? 'text.maturity-consistency-clean' : 'text.maturity-consistency-faults',
-    because: 'text.maturity-consistency-because'
+    readingKey: faults === 0 ? 'figure.text.maturity-consistency-clean' : 'figure.text.maturity-consistency-faults',
+    because: 'figure.text.maturity-consistency-because'
   }
 }
 
@@ -117,7 +117,7 @@ function consistency(source: FigureSource, cost: FigureCost): MaturityAxis {
 function reuse(score: FigureScore): MaturityAxis {
   const { distinct, parts, saved } = score.reuse
   if (parts === 0) {
-    return { key: 'reuse', blocked: 'text.maturity-blocked-no-parts' }
+    return { key: 'reuse', blocked: 'figure.text.maturity-blocked-no-parts' }
   }
 
   return {
@@ -125,7 +125,7 @@ function reuse(score: FigureScore): MaturityAxis {
     // ratio 가 낮을수록 많이 되쓴다 — 뒤집어서 높은 쪽이 좋게 만든다
     ratio: 1 - distinct / parts,
     reading: String(saved),
-    because: 'text.maturity-reuse-because'
+    because: 'figure.text.maturity-reuse-because'
   }
 }
 
@@ -148,7 +148,7 @@ function detail(source: FigureSource, cost: FigureCost): MaturityAxis {
     // 절반쯤 쓴 것을 제일 좋게 본다. 텅 비어도, 넘쳐도 등급과 안 맞는다.
     ratio: used > 1 ? Math.max(0, 2 - used) : Math.min(1, used * 2),
     reading: `${cost.parts} / ${limit}`,
-    because: 'text.maturity-detail-because'
+    because: 'figure.text.maturity-detail-because'
   }
 }
 
@@ -162,7 +162,7 @@ function detail(source: FigureSource, cost: FigureCost): MaturityAxis {
  * **아무 형상도 보여 줄 수 없는 상태**다. 축 자체가 아직 없는 것이다.
  */
 function reactive(source: FigureSource): MaturityAxis {
-  return { key: 'reactive', blocked: 'text.maturity-blocked-no-binding' }
+  return { key: 'reactive', blocked: 'figure.text.maturity-blocked-no-binding' }
 }
 
 /**
@@ -205,7 +205,7 @@ function reactive(source: FigureSource): MaturityAxis {
 function readable(source: FigureSource, cost: FigureCost): MaturityAxis {
   const regions = topViewRegions(source)
   if (regions.total === 0) {
-    return { key: 'readable', blocked: 'text.maturity-blocked-no-parts' }
+    return { key: 'readable', blocked: 'figure.text.maturity-blocked-no-parts' }
   }
 
   // 배경도 한 구역으로 센다 — 발자국을 얼마나 채우나가 식별성의 일부다.
@@ -221,7 +221,7 @@ function readable(source: FigureSource, cost: FigureCost): MaturityAxis {
     key: 'readable',
     ratio: Math.min(1, entropy / ceiling),
     reading: `${regions.byMaterial.size}`,
-    because: 'text.maturity-readable-because'
+    because: 'figure.text.maturity-readable-because'
   }
 }