quad/.claude/base/ui-shorthand-plan.md

UI 편의 숏핸드 (UICorner/UIPadding/UIScale) — 인라인 적용

상태: base — 기능 필요 여부·이름·메커니즘·패키지 배치·store-bind 가능성까지 전부 확정(2026-08-07 문서 정리에서 research/→base/ 승격). 남은 건 구현 단계의 세부 시그니처뿐.

배경

사용자 기억: v1을 쓸 때 "UICorner/UIPadding/UIScale 같은 걸 직접 Instance.new로 만들어 Parent하는 귀찮은 작업 없이, Frame 안에 인라인으로 넣기만 해도 CSS 스타일처럼 적용됐다 — 코드가 줄고 읽기도 편해서 꽤 괜찮았다"는 것. v1 소스(.claude/initreq/quad)와 PA님 코드 (.claude/initreq/artworks)를 서브에이전트로 조사해 확인.

v1 실제 메커니즘 (조사 완료)

class.lua의 SetProperty/GetProperty(38109행)와 ProcessQuadProperty (134213행)에 하드코딩된 if/elseif 분기로 특수 문자열 키 5종을 지원했음 — Corner = 8 → 숫자 하나, 기존 UICorner 자식이 있으면 재사용, 없으면 Instance.new("UICorner", item)으로 생성(Name = "_quad_round"), CornerRadius = UDim.new(0, value) 설정. PaddingAll/PaddingAllOffset, Scale도 동일 패턴(UIPadding/UIScale, _quad_padding/_quad_scale). 값 모양은 항상 리터럴 하나(숫자/UDim) — 테이블도 __type 태그도 아님. v1엔 이 5종과 별개로 RoundSize(이미지 9-slice 라운드 트릭, UICorner와는 전혀 다른 메커니즘)도 있었으나 이건 드롭 확정 — 자세한 사유는 archive/ui-shorthand-roundsize-dropped.md 참고, 이 문서에서는 반복하지 않음.

UIListLayout/UIGridLayout/flex 전용 숏핸드는 v1에 없었음 — ProcessQuadProperty의 범용 자식 나열 분기(배열 인덱스로 놓인 Instance/ Class 결과를 자동 mount)로 UIListLayout{...}을 그냥 직접 나열했을 뿐, List = true 같은 전용 축약 문법은 레포 전체(PA님 코드 포함)에서 찾지 못했음. quad-v2도 이 부분은 이미 있는 children-array + 인스턴스 생성 문법으로 그대로 커버됨 — 새로 설계할 것 없음.

결론 — 이름은 UICorner/UIPadding/UIScale로 확정 (프리픽스 필요)

기능은 여전히 필요: UICorner가 Roblox 네이티브 Instance가 됐어도 "별도 Instance를 만들어 부모에 Parent해야 한다"는 구조적 번거로움 자체는 없어지지 않으므로, 이 숏핸드의 존재 이유는 그대로 유효 — 사용자 재확정("UIScale 같은 건 여전히 별도의 Instance고 부모 Frame에 영향을 주는 구조, 숏핸드는 여전히 필요하다").

이름은 v1의 Corner/PaddingAll/Scale을 그대로 안 가져오고 실제 Roblox Instance 이름과 맞춘 UICorner/UIPadding(+UIPaddingOffset)/ UIScale로 확정 — v1식 짧은 이름을 그대로 쓰면 Modifier 체이닝 메소드(mod:Corner(8))가 "진짜 UICorner를 만드는 숏핸드"인지 그냥 우연히 비슷한 이름의 부가 Modifier 필드인지 구분이 안 됨(사용자 지적). 접두어 UI를 붙이면 실제 대응하는 Roblox Instance 클래스 이름과 1:1로 읽혀서 이 모호함 자체가 사라짐 — Frame { UICorner = 8 }, mod:UICorner(8).

메커니즘 — 새 아키텍처 개념 불필요

이미 있는 pluggable Handler로 그대로 커버됨. UICorner/UIPadding/ UIScale 같은 특수 키를 인식하는 Handler(isHandlable이 그 키를 매칭)가 "이름 붙은 자식을 찾거나 만들고 그 자식의 프로퍼티를 세팅"을 process(inst, k, v, index)에 구현([2026-08-14 세션] 그 마지막 "세팅"은 직접 대입이 아니라 Dispatch.process(child, prop, ..., 1)로 되돌려주는 위임으로 확정 — 아래 "Tween 지원" 절) — v1의 하드코딩 if/elseif 대신 정식 핸들러 계약(isHandlable/ priority/process, 2026-08-13 다섯 번째 세션 전까진 retract가 별도 필드였음)을 따르는 것만 다름. modifier-plan.md가 이미 예시로 든 mod:UICorner(8)은 이 특수 키를 flatten해서 props에 꽂아넣는 사탕 문법일 뿐, 실제 처리는 이 Handler가 함 — Modifier를 안 거치고 Frame { UICorner = 8 }처럼 순수 인라인 키로 직접 써도(v1처럼) 동일하게 작동함, architecture.md의 [AttributeKey "Name"]류 특수 키와 같은 층위. 자동 생성된 자식은 기존 관례대로 _/QUAD_ 접두어 네이밍 (research/debug-tooling-plan.md 9번, v1의 _quad_round류 그대로 재사용).

[보강, 2026-08-09 열한 번째 세션] mod:UICorner(8)류 체이닝이 실제로 타입체크되려면, 생성되는 FrameModifier류 정적 타입의 메소드 목록에 UICorner/UIPadding/UIScale이 (진짜 프로퍼티들과 나란히) 포함돼 있어야 함 — 순수 런타임 관점(제네릭 __index가 처리)에선 문제없지만, 타입 레벨에선 별도로 챙겨야 하는 항목. quad-roblox의 각종 타입(D 인스턴스 타입, Modifier 타입 등)이 Roblox API 덤프를 읽어 Luau 타입 파일을 구워내는 스크립트로 생성될 예정이라(구현 단계 결정 사항) — 이 스크립트가 실제 Roblox 프로퍼티뿐 아니라 이 3개 숏핸드 키도 각 Modifier 타입의 메소드 목록에 끼워 넣도록 챙기면 됨, 새로 설계할 게 없는 구현 체크리스트 항목.

기존 자식과의 매칭 기준(2026-08-06 감사에서 지적된 항목, 여기서 같이 확정): 재사용 대상은 quad가 이전에 만든 고정 이름(_quad_corner류) 자식으로 한정 — 타입만 보고(UICorner이기만 하면 아무거나) 재사용하지 않음. 사용자가 직접 만든 UICorner를 quad가 멋대로 건드리는 부작용을 피하기 위함.

[요구 추가, 2026-08-18 구현 전 QA] 다시 찾을 때 FindFirstChild 대신 Relate에 저장해둔 참조를 쓸 것. 사용자 요구: "FindFirstChild 는 비용이 ref 저장보단 비쌈. spring 등으로 움직일 수도 있다 생각하면 릴레이션으로 저장하는것도 좋은 생각."

• 조회 경로: (inst, 숏핸드키) → child를 Relate에 저장해두고 그걸로 되찾는다. Relate는 inst를 weak 키로 쓰므로 부모가 죽으면 항목도 자연히 빠진다(base/relate-plan.md).
• 고정 이름 규약을 없애자는 뜻은 아님 — 이름(_quad_corner류)은 디버깅 가시성(research/debug-tooling-plan.md)과 "사용자가 만든 UICorner를 건드리지 않는다"는 위 판정에 여전히 필요하다. 이름은 표시·판정용, Relate는 조회용으로 역할이 갈린다.
• [해소, 2026-08-20 구현 전 QA 4라운드 UI-5] 자식도 반드시 gcconn/gchold 셋업을 거친다 — 안 거치면 이 숏핸드 자체가 애초에 동작을 못 한다. 원래 "구현 시 확인할 것"으로 열어뒀던 항목인데, 사용자 판정으로 닫힘: "애초에 똑같이 process 로 위임하는 이상, gcconn/gchold 없으면 옵저버 바인딩 부터 실패함. 일반 요소처럼 똑같이 UI...{} 처럼 생성되어도 되고, 어떤 방식으로든 gcconn/gchold 가 셋업되는게 맞음."
  • 논거: 아래 "Tween 지원" 절대로 이 숏핸드는 자식 프로퍼티를 직접 쓰지 않고 Dispatch.process(child, prop, v, 1)로 위임하는데, 그 값이 State면 StoreBind가 bindLifetime(child, observer)를 부른다 — 그 시점에 child에 gcconn/gchold가 없으면 거기서 곧바로 실패한다. 즉 "조용히 미아가 되는" 시나리오가 아니라 즉시 드러나는 전제 조건이고, 숏핸드가 자식을 만드는 경로도 일반 인스턴스 생성과 같은 셋업을 타야 한다.
  • 따라서 ensureManagedChild는 자식을 만들 때 일반 인스턴스 생성과 동일한 경로(gcconn/gchold 셋업 포함)를 써야 한다 — 별도 확인 항목이 아니라 구현이 반드시 만족해야 하는 계약.
• 부수 요구 — 숏핸드가 만든 자식의 프로퍼티 세팅도 Dispatch에 위임: "각 숏핸드가 만들어낸 요소의 프로퍼티 세팅은 새로운 dispatch.process(target,k,v) 로 위임해 tween 등이 자연스럽게 가능." 즉 숏핸드 Handler가 자식 프로퍼티를 직접 쓰지 말고 Dispatch.process(child, k, v, 1)로 넘기면 State/Tween 래핑이 공짜로 따라온다.

v가 nil인 경우 — process가 직접 자식 제거, 반환 클로저는 관여 안 함 (2026-08-07 여덟 번째 세션)

modifier-plan.md의 None 센티널(base/dispatch-core-plan.md의 NoneHandler 재귀 재디스패치 절 참고)이 최종적으로 이 Handler의 process(inst, k, nil)을 호출하는 구체 사례 — 이 Handler에서 "v가 nil"은 만들어둔 _quad_corner류 자식이 있으면 그냥 지우는 것으로 확정. 일반 프로퍼티 핸들러와 달리 이 숏핸드는 실제 Instance를 만들어 붙이는 쪽이라 "nil = 셋 안 함"이 곧 "만들어둔 게 있으면 치운다"는 뜻이 됨.

• 이건 반환 클로저가 아니라 process 자신의 로직 — [정정, 2026-08-12 열한 번째 세션, 2026-08-13 다섯 번째 세션에 클로저 반환 계약으로 서술 갱신] 그 클로저는 store 재발행마다 항상 불리지만(핸들러 타입이 안 바뀌어도, dispatch-core-plan.md 일반 retract 계약 절 정정분 참고), 이 Handler는 process(inst,k,v,index) 자체가 v가 nil이든 숫자든 전부 완결적으로 처리하므로(있으면 지우거나 만들거나) 반환 클로저가 할 일이 없어 function() end이면 충분 — 일반 프로퍼티 핸들러가 no-op 클로저를 반환하는 것과 같은 이유. 값이 나중에 다시 숫자로(2→nil→3처럼) 바뀌면 process가 다시 자식을 만들면 그만이라 클로저 쪽에 별도로 구현할 게 없음.
• 캐비엇: 이 왔다갔다가 잦으면(예: 반응형 State가 nil과 숫자 사이를 자주 토글) 매번 Instance 생성/제거 비용이 그대로 듦 — Tween처럼 무거운 API는 아니지만 공짜도 아니므로, 잦은 토글이 예상되는 값을 이 숏핸드에 직접 물리는 건 문서화 시점에 캐비엇으로 명시할 것(지금은 메모만).

Tween 지원 — 자식 프로퍼티를 Dispatch.process로 다시 흘려보내면 공짜 (2026-08-14 세션 확정)

[역전] "트윈처럼 애니메이션까지 지원할 필요는 없음"이라던 아래 store-bind 절의 서술은 폐기. 그 판단은 Tween이 아직 독립 Dispatch 핸들러였던 시절(우선순위를 다투는 특수 bind key, archive/tween-special-bind-key-reversed.md) 기준이라 "이 숏핸드도 그 경쟁에 끼워 넣어야 하나"가 비용이었는데, 2026-08-10 재설계로 Tween이 값-레벨 래퍼 Tween<T> + PropertyHandler 내부 분기가 되면서(base/tween-plan.md) 그 비용이 통째로 사라짐 — 이제는 숏핸드가 자식 프로퍼티 세팅을 자기 손으로 하지 않고 Dispatch에 되돌려주기만 하면 Tween이 저절로 따라옴.

메커니즘 — 인스턴스 관리 후 process로 위임:

-- 개념 스케치. Handler 계약은 base/dispatch-core-plan.md가 정본
function UICornerHandler.process(inst, k, v, index)
    if v == nil then
        -- 기존 규칙 그대로: 만들어둔 자식이 있으면 지움(아래 "v가 nil인 경우" 절)
        destroyManagedChild(inst, k)
        return function() end
    end
    local child = ensureManagedChild(inst, k)   -- 없으면 Instance.new + Parent, 있으면 재사용
    Dispatch.process(child, "CornerRadius", mapTweenValue(v, toUDim), 1)
    return function(hint)
        if hint == nil then destroyManagedChild(inst, k) end
    end
end

• process 도중에 대상 inst를 바꾸는 것은 UB가 아님(사용자 확정) — 키가 바뀔 수 있는 것과 정확히 같음. chains가 (inst,k) 쌍으로 인덱싱되므로 (inst, "UICorner") → (child, "CornerRadius") 위임은 Dispatch 입장에서 Attribute 그룹이 다른 키로 위임하는 것과 구조적으로 동일한 일이고, 새 체인이라 인덱스는 1부터. 일반 규칙은 base/dispatch-core-plan.md의 "인덱스의 의미" 절에 같이 명문화해뒀음.
• Tween 해석 코드를 여기 복제하지 않는 게 핵심 이득 — Tween<T>를 실제로 읽는 코드는 여전히 PropertyHandler 하나뿐이라는 base/tween-plan.md의 불변식이 유지됨. 3-상태 릴레이션 슬롯 ({Tween, Value} | true | nil), Tween.Cancel/Tween.Finish override 정책, "첫 세팅은 애니메이션 없이 즉시" 규칙까지 전부 (child, prop) 자리에서 그대로 재사용됨 — 이 문서가 따로 정할 게 없음.
• 타입 대수도 그대로 — 숏핸드 키의 값 타입이 number였다면 이제 number | Tween<number> | State<number | Tween<number>>가 됨 (T' = T | Tween<T> 치환, tween-plan.md "타입 대수" 절). StoreBind가 State 레이어를 먼저 다 풀어내므로 이 Handler가 실제로 보는 v는 number 아니면 Tween<number> 둘 중 하나.

한 가지 진짜로 필요한 부품 — wrap을 Tween 위로 들어올리기. [승격, 2026-08-20 구현 전 QA 4라운드 UI-8] 아래 로컬 헬퍼 mapTweenValue는 Tween 자신의 공개 메소드 :Mapped(fn)으로 올라갔다(이름은 2026-08-21 5라운드 TW-2에서 확정) — base/tween-plan.md의 "Tween<T>:Mapped(fn)" 절이 소스. 이 문서에 로컬 헬퍼로 두면 같은 변환이 다른 숏핸드/백엔드에서 또 복제되므로, 값 타입 자신이 제공하는 게 맞다는 사용자 판단. 아래 스케치는 그 메소드가 하는 일을 풀어 쓴 것으로만 읽을 것(isTween(v) 분기는 호출부에 남고, Tween이면 v:Mapped(wrap), 아니면 wrap(v)): 숏핸드는 "스칼라를 받아 자식 프로퍼티 타입으로 감싸는" 변환을 갖고 있음(UICorner = 8 → CornerRadius = UDim.new(0, 8), 열린 질문 절의 룩업 테이블 wrap=fn). v가 Tween<number>면 그 변환을 Tween을 벗기지 않고 .Value에만 적용해야 함:

-- Tween<T>는 immutable 값 객체라 clone 후 Value만 교체(Brand 재설정은 Tween()이 함)
local function mapTweenValue(v, wrap)
    if isTween(v) then
        local opts = table.clone(v)
        opts.Value = wrap(v.Value)
        return Tween(opts)
    end
    return wrap(v)
end

• UIScale처럼 wrap이 항등(스칼라를 그대로 Scale에 씀)인 키는 이 헬퍼를 거쳐도 결과가 같으므로 분기 없이 일관되게 씀.
• UIPadding처럼 자식의 프로퍼티 여러 개(PaddingTop/Bottom/ Left/Right)에 같은 값을 쓰는 키는 각 프로퍼티마다 Dispatch.process를 따로 부름 — 각자 독립된 (child, prop) 체인이 되고, PropertyHandler의 트윈 슬롯도 프로퍼티별로 따로 잡혀서 자연스럽게 4개가 같이 애니메이션됨.
• Tween 값 자체는 quad-base, 이 숏핸드 Handler는 quad-roblox — isTween/Tween()을 base에서 가져다 쓰는 것뿐이라 패키지 경계 (tween-plan.md "패키지 경계" 절)와 안 부딪힘.

캐비엇 — 자식이 새로 만들어진 사이클에서는 트윈이 안 걸린다(의도된 동작). PropertyHandler의 "첫 세팅은 애니메이션 없이 즉시"(prev == nil) 규칙이 (child, prop) 기준이므로, UICorner가 nil↔숫자를 오가며 자식이 파괴/ 재생성되면 그 직후 첫 값은 트윈 없이 스냅됨. 이건 버그가 아니라 그 규칙이 막으려는 것(기본값에서 목표값으로 날아오는 진입 애니메이션)과 정확히 같은 상황 — 계속 애니메이션되길 원하면 자식이 살아있도록 nil로 내리지 말고 값만 바꿀 것.

[정정, 2026-08-20 구현 전 QA 4라운드 UI-11] 자식을 파괴할 때 Dispatch.retractFrom(child, prop, 1)을 "정석"으로 요구하지 않는다 — 실익이 없다. 옛 서술은 "실행 중인 엔진 Tween이 남아있을 수 있으므로 같이 부르는 게 정석"이었는데, 사용자 판정: "자식 파괴 시 사실 Tween 은 엔진에 의해 자동 멈춤/무효/삭제 처리되고, 트윈 자체가 retract 되어도 아무것도 안 하는 nop 라 의미가 없을것이다."

• 두 겹으로 무의미하다: (a) Roblox 엔진이 Destroy 시점에 그 인스턴스에 걸린 Tween을 알아서 정리하고(base/lifecycle-pattern.md의 "retract는 Destroy 시점에 필요 없는 이유가 엔진 레벨에서 한 번 더 보강됨" 절), (b) PropertyHandler가 반환하는 retractor는 애초에 몸체가 no-op이라(base/tween-plan.md의 "왜 retract가 더 이상 필요 없는가" 절) 불러봐야 하는 일이 없다.
• 그래도 호출이 금지되는 건 아니다 — retractor 안에서 다른 키에 대한 retractFrom을 부르는 것 자체는 여전히 허용된 경로다 (base/dispatch-core-plan.md의 retract 계약 — 금지된 건 같은 (inst,k)에 대한 재진입). 다만 이 자리에서 필요하지 않다는 것.
• chains는 child에 대해 weak-keyed라 자식을 버리면 결국 GC된다 — 명시적 정리가 필요한 자원이 이 자리엔 없다.

store-bind — 이 숏핸드도 지원

v1에서도 Corner/PaddingAll/Scale은 store 값으로 바인드 가능했음 (myStore "key" 체이닝으로 다른 프로퍼티와 동일하게 취급됨) — quad-v2도 이 능력을 유지한다. [정정, 2026-08-14 세션] 이 절의 원 서술은 "트윈처럼 애니메이션까지 지원할 필요는 없음(API 표면만 복잡해짐) — 그냥 값이 바뀌면 프로퍼티를 다시 세팅하는 정도로 충분"이었으나, 위 "Tween 지원" 절에서 뒤집혔음(자식 프로퍼티를 Dispatch.process로 되돌려주면 Tween이 공짜로 따라오므로 "안 하는 게 더 비싸지는" 상황이 됨). 구현 비용은 여전히 낮음: 각 Handler가 process에서 "이전에 자기가 찾거나 만든 자식 Instance"를 얻어야 하는데, 이건 이미 base가 범용 유틸로 제공하기로 확정한 per-instance weak-keyed 저장소 (Relate:SetStrong(inst,k,...), base/relate-plan.md/base/dispatch-core-plan.md "핸들러 내부 상태 저장" 절)를 그대로 재사용하면 됨 — PropertyHandler가 실행 중인 Tween 상태를 기억해두는 것과 정확히 같은 패턴. 새 메커니즘 발명 불필요, 이미 있는 "store 바인드는 pluggable 바인드를 재실행하는 래핑" 원칙 (base/dispatch-core-plan.md "확정된 디스패치 모델" 절)이 그대로 적용됨.

패키지 배치 — quad-roblox 코어에 직접 포함, 확정

"트윈도 인스턴스 생성/제어를 직접 구현 가능한 걸 하나로 묶어 쉽게 쓰게 합친 것 — 너무 잘게 쪼개 오버엔지니어링하기보다 확실히 하나로 코어에 넣어도 충분하다, opt-out할 이유가 별로 없다"는 게 사용자 판단 — 작고 항상 켜져 있어도 비용이 무시할 만한 편의 기능은 별도 opt-out 패키지로 쪼개지 말고 quad-roblox 코어에 직접 포함한다는 원칙으로 확정(이미 계획된 Tween 처리 로직이 같은 모양이라는 게 근거). 이 원칙은 일반화해서 재사용 가능 — 앞으로 비슷한 "작은 인스턴스 편의 기능"이 제안되면 quad-roblox-util 같은 걸 새로 만들지 않고 이 선례를 따르면 됨.

중요도: 낮음("이건 나중에도 쉽게 구현됨" — 사용자) — 지금 M0 우선순위를 바꿀 이유는 없음, M10(Handlers/Attribute 등) 전후로 다른 세부 Handler와 함께 구현하면 충분.

남은 열린 질문 (단순화 후보, 사소함)

• UICorner/UIPadding/UIScale 3개 거의 동일한 형태의 Handler를 각각 만들지, {key -> {ChildClassName, ChildDefaultName, Properties, wrap=fn}} 룩업 테이블로 구동되는 단일 Handlers/InstanceShorthand.luau로 통합할지 (Properties가 단수가 아니라 목록인 이유는 UIPadding이 자식 프로퍼티 4개에 같은 값을 쓰기 때문 — 위 "Tween 지원" 절) — research/pre-implementation-audit.md 3-2번 참고, 강제 사항 아님, 구현 시점에 결정할 정도의 사소한 개선 후보.