@hjmds/design-contracts 1.41.2 → 1.43.0

package/dist/top.d.ts

@@ -14,6 +14,13 @@
  * 계약을 합치지 않았다 — 합치면 "이 Section이 화면의 h1인가"를 매번 물어야 한다.
  */
 export type TopSize = "medium" | "large";
+/**
+ * `\n` in the title (2026-10-23). `collapse`(기본): 줄바꿈 문자는 공백이 되고 폭에 따라 자연스럽게 감긴다 — Web이 원래
+ * 그렇게 그렸고, Native만 `\n`을 그대로 그려 두 플랫폼이 달랐다. `preserve`: 제품이 의도한 줄바꿈을 지킨다(히어로 문구).
+ * 어느 쪽이든 제목 이름은 한 문장으로 읽힌다 — 줄은 공백 하나로 이어진다. 포트폴리오 사이트 히어로가 `white-space: pre-line`
+ * span을 Heading 안에 넣느라 Top을 채택하지 못했다.
+ */
+export type TopTitleLineBreaks = "collapse" | "preserve";
 export type TopDescriptor = Readonly<{
     title: string;
     /** 제목 위 한 줄. 카테고리·단계처럼 제목을 한정하는 짧은 말. */
@@ -21,6 +28,8 @@ export type TopDescriptor = Readonly<{
     /** 제목 아래 보조 문장. 길면 줄바꿈되며 잘리지 않는다. */
     description?: string;
     size?: TopSize;
+    /** 제목 안 `\n`의 처리. 기본 `collapse`. */
+    titleLineBreaks?: TopTitleLineBreaks;
     /**
      * 문서 구조상의 제목 단계. 화면당 하나인 Top은 `1`이 기본이지만, 한 라우트가
      * 여러 화면을 담는 경우(시트 안의 화면 등) 제품이 낮출 수 있다.
@@ -30,8 +39,18 @@ export type TopDescriptor = Readonly<{
 export declare const topDefaults: {
     readonly size: "large";
     readonly headingLevel: 1;
+    readonly titleLineBreaks: "collapse";
 };
 export declare function validateTopDescriptor(descriptor: TopDescriptor): void;
+export type ResolvedTopTitle = Readonly<{
+    /** Text to draw. `preserve` keeps one `\n` between trimmed, non-empty lines; `collapse` has none. */
+    text: string;
+    /** The heading's spoken name: the same lines joined by one space, so an intended break never cuts the title. */
+    accessibleName: string;
+    /** Lines as drawn (one entry when collapsed). */
+    lines: readonly string[];
+}>;
+export declare function resolveTopTitle(descriptor: TopDescriptor): ResolvedTopTitle;
 /**
  * `large`는 화면의 첫 제목, `medium`은 시트·모달 안의 첫 제목이다. 두 단계뿐인 이유는
  * 세 번째가 필요해지는 자리가 곧 `Section`이기 때문이다 — 크기를 더 늘리는 대신 다른
@@ -96,7 +115,7 @@ export declare const topRecipe: {
 export declare const topBehavior: {
     /** 상태 축이 없다 — 화면이 제목을 바꾸면 그냥 다른 문자열을 넘긴다. */
     readonly controlled: readonly [];
-    readonly inputs: readonly ["title", "eyebrow", "description", "size", "headingLevel"];
+    readonly inputs: readonly ["title", "eyebrow", "description", "size", "headingLevel", "titleLineBreaks"];
     readonly stateAxes: {};
     readonly web: {
         readonly roles: readonly ["heading"];
@@ -108,6 +127,6 @@ export declare const topBehavior: {
         readonly states: readonly [];
         readonly actions: readonly [];
     };
-    readonly scenarios: readonly ["the-title-is-a-real-heading-element-at-the-declared-level-not-styled-text", "top-is-body-content-that-scrolls-away-while-topbar-is-fixed-chrome", "description-wraps-instead-of-truncating-so-large-text-never-hides-the-question", "a-trailing-action-shares-the-title-row-and-drops-below-it-when-space-runs-out", "eyebrow-never-carries-information-the-title-does-not-repeat-in-some-form"];
+    readonly scenarios: readonly ["the-title-is-a-real-heading-element-at-the-declared-level-not-styled-text", "top-is-body-content-that-scrolls-away-while-topbar-is-fixed-chrome", "description-wraps-instead-of-truncating-so-large-text-never-hides-the-question", "preserved-title-line-breaks-change-only-the-drawing-and-the-heading-name-stays-one-sentence", "a-trailing-action-shares-the-title-row-and-drops-below-it-when-space-runs-out", "eyebrow-never-carries-information-the-title-does-not-repeat-in-some-form"];
 };
 //# sourceMappingURL=top.d.ts.map

package/dist/top.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"top.d.ts","sourceRoot":"","sources":["../src/top.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH,eAAO,MAAM,WAAW;;;CAGiD,CAAC;AAQ1E,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAkBrE;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAoBpB,uDAAuD;;;;;CAexD,CAAC;AAEF,eAAO,MAAM,WAAW;IACtB,6CAA6C;;;;;;;;;;;;;;;CAaV,CAAC"}
+{"version":3,"file":"top.d.ts","sourceRoot":"","sources":["../src/top.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AACzC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oCAAoC;IACpC,eAAe,CAAC,EAAE,kBAAkB,CAAC;IACrC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH,eAAO,MAAM,WAAW;;;;CAIsF,CAAC;AAQ/G,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAyBrE;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;IACb,gHAAgH;IAChH,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC,CAAC;AAEH,wBAAgB,eAAe,CAAC,UAAU,EAAE,aAAa,GAAG,gBAAgB,CAQ3E;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAoBpB,uDAAuD;;;;;CAexD,CAAC;AAEF,eAAO,MAAM,WAAW;IACtB,6CAA6C;;;;;;;;;;;;;;;CAcV,CAAC"}

package/dist/top.js

@@ -3,6 +3,7 @@ import { semanticColors } from "./semantic-colors.js";
 export const topDefaults = {
     size: "large",
     headingLevel: 1,
+    titleLineBreaks: "collapse",
 };
 function assertNonEmpty(value, field) {
     if (typeof value !== "string" || value.trim().length === 0) {
@@ -22,11 +23,25 @@ export function validateTopDescriptor(descriptor) {
     if (descriptor.size !== undefined && descriptor.size !== "medium" && descriptor.size !== "large") {
         throw new TypeError(`Unsupported Top size: ${String(descriptor.size)}`);
     }
+    if (descriptor.titleLineBreaks !== undefined &&
+        descriptor.titleLineBreaks !== "collapse" &&
+        descriptor.titleLineBreaks !== "preserve") {
+        throw new TypeError(`Unsupported Top titleLineBreaks: ${String(descriptor.titleLineBreaks)}`);
+    }
     if (descriptor.headingLevel !== undefined &&
         ![1, 2, 3].includes(descriptor.headingLevel)) {
         throw new TypeError(`Unsupported Top headingLevel: ${String(descriptor.headingLevel)}`);
     }
 }
+export function resolveTopTitle(descriptor) {
+    validateTopDescriptor(descriptor);
+    const lines = descriptor.title.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+    const accessibleName = lines.join(" ");
+    const preserve = (descriptor.titleLineBreaks ?? topDefaults.titleLineBreaks) === "preserve";
+    return preserve
+        ? { text: lines.join("\n"), accessibleName, lines }
+        : { text: accessibleName, accessibleName, lines: [accessibleName] };
+}
 /**
  * `large`는 화면의 첫 제목, `medium`은 시트·모달 안의 첫 제목이다. 두 단계뿐인 이유는
  * 세 번째가 필요해지는 자리가 곧 `Section`이기 때문이다 — 크기를 더 늘리는 대신 다른
@@ -59,7 +74,7 @@ export const topRecipe = {
 export const topBehavior = {
     /** 상태 축이 없다 — 화면이 제목을 바꾸면 그냥 다른 문자열을 넘긴다. */
     controlled: [],
-    inputs: ["title", "eyebrow", "description", "size", "headingLevel"],
+    inputs: ["title", "eyebrow", "description", "size", "headingLevel", "titleLineBreaks"],
     stateAxes: {},
     web: { roles: ["heading"], keyboard: [], focus: "none" },
     native: { roles: ["header"], states: [], actions: [] },
@@ -67,6 +82,7 @@ export const topBehavior = {
         "the-title-is-a-real-heading-element-at-the-declared-level-not-styled-text",
         "top-is-body-content-that-scrolls-away-while-topbar-is-fixed-chrome",
         "description-wraps-instead-of-truncating-so-large-text-never-hides-the-question",
+        "preserved-title-line-breaks-change-only-the-drawing-and-the-heading-name-stays-one-sentence",
         "a-trailing-action-shares-the-title-row-and-drops-below-it-when-space-runs-out",
         "eyebrow-never-carries-information-the-title-does-not-repeat-in-some-form",
     ],

package/dist/top.js.map

@@ -1 +1 @@
-{"version":3,"file":"top.js","sourceRoot":"","sources":["../src/top.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport { heading, spacing, typography } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * 화면 본문의 **첫 블록**이다. `TopBar`(상단 내비게이션 바)와 다른 자리이고, 그 차이가\n * 이 계약의 존재 이유다.\n *\n * - `TopBar`는 화면에 고정된 크롬이다 — 뒤로가기, 화면 이름, 액션. 스크롤과 무관하게\n *   붙어 있고 safe area를 다룬다.\n * - `Top`은 본문이다 — 스크롤과 함께 올라가고, 사용자가 \"이 화면이 무엇을 묻는지\"\n *   읽는 문장이 여기 있다. 토스 TDS가 \"Top과 ListRow로 화면 대부분을 만든다\"고\n *   말하는 그 Top이고, 지금까지 BurnTok `AppScreenHeader`·Taground `screen-shell`·\n *   Diairy `DetailPanel`이 각자 다시 만들던 블록이다.\n *\n * `Section`과도 다르다. Section은 본문 **중간**의 묶음 제목이라 heading level이 화면\n * 구조에 종속되지만, Top은 화면당 하나뿐인 첫 제목이라 기본이 `h1`이다. 그래서 두\n * 계약을 합치지 않았다 — 합치면 \"이 Section이 화면의 h1인가\"를 매번 물어야 한다.\n */\nexport type TopSize = \"medium\" | \"large\";\n\nexport type TopDescriptor = Readonly<{\n  title: string;\n  /** 제목 위 한 줄. 카테고리·단계처럼 제목을 한정하는 짧은 말. */\n  eyebrow?: string;\n  /** 제목 아래 보조 문장. 길면 줄바꿈되며 잘리지 않는다. */\n  description?: string;\n  size?: TopSize;\n  /**\n   * 문서 구조상의 제목 단계. 화면당 하나인 Top은 `1`이 기본이지만, 한 라우트가\n   * 여러 화면을 담는 경우(시트 안의 화면 등) 제품이 낮출 수 있다.\n   */\n  headingLevel?: 1 | 2 | 3;\n}>;\n\nexport const topDefaults = {\n  size: \"large\",\n  headingLevel: 1,\n} as const satisfies Readonly<{ size: TopSize; headingLevel: 1 | 2 | 3 }>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`Top ${field} must not be empty`);\n  }\n}\n\nexport function validateTopDescriptor(descriptor: TopDescriptor): void {\n  if (descriptor === null || typeof descriptor !== \"object\") {\n    throw new TypeError(\"Top descriptor must be an object\");\n  }\n  assertNonEmpty(descriptor.title, \"title\");\n  if (descriptor.eyebrow !== undefined) assertNonEmpty(descriptor.eyebrow, \"eyebrow\");\n  if (descriptor.description !== undefined) {\n    assertNonEmpty(descriptor.description, \"description\");\n  }\n  if (descriptor.size !== undefined && descriptor.size !== \"medium\" && descriptor.size !== \"large\") {\n    throw new TypeError(`Unsupported Top size: ${String(descriptor.size)}`);\n  }\n  if (\n    descriptor.headingLevel !== undefined &&\n    ![1, 2, 3].includes(descriptor.headingLevel)\n  ) {\n    throw new TypeError(`Unsupported Top headingLevel: ${String(descriptor.headingLevel)}`);\n  }\n}\n\n/**\n * `large`는 화면의 첫 제목, `medium`은 시트·모달 안의 첫 제목이다. 두 단계뿐인 이유는\n * 세 번째가 필요해지는 자리가 곧 `Section`이기 때문이다 — 크기를 더 늘리는 대신 다른\n * 컴포넌트를 쓰라는 신호로 둔다.\n */\nexport const topRecipe = {\n  slots: [\"root\", \"eyebrow\", \"title\", \"description\", \"trailing\"] as const,\n  defaults: { size: topDefaults.size },\n  sizes: {\n    medium: { title: typography.titleLarge, paddingTop: spacing.md, paddingBottom: spacing.sm },\n    // The screen's first title uses the HJM ceiling, `heading.level3` (24). It was `heading.level2` (32) until the\n    // display tier was removed (2026-10-17 user decision, \"글자 너무 커\").\n    large: { title: heading.level3, paddingTop: spacing.xl, paddingBottom: spacing.md },\n  },\n  eyebrow: {\n    color: semanticColors.content.brand,\n    textVariant: \"label\" as const,\n    marginBottom: spacing.xxs,\n  },\n  title: { color: semanticColors.content.primary },\n  description: {\n    color: semanticColors.content.body,\n    textVariant: \"body\" as const,\n    marginTop: spacing.xs,\n  },\n  /** 제목 줄 오른쪽 보조 행동. 본문이므로 TopBar처럼 아이콘 전용을 강제하지 않는다. */\n  trailing: { gap: spacing.xs },\n  gap: spacing.xs,\n} as const satisfies {\n  slots: readonly [\"root\", \"eyebrow\", \"title\", \"description\", \"trailing\"];\n  defaults: { size: TopSize };\n  sizes: Readonly<{\n    medium: { title: typeof typography.titleLarge; paddingTop: number; paddingBottom: number };\n    large: { title: typeof heading.level3; paddingTop: number; paddingBottom: number };\n  }>;\n  eyebrow: { color: ColorReference; textVariant: \"label\"; marginBottom: number };\n  title: { color: ColorReference };\n  description: { color: ColorReference; textVariant: \"body\"; marginTop: number };\n  trailing: { gap: number };\n  gap: number;\n};\n\nexport const topBehavior = {\n  /** 상태 축이 없다 — 화면이 제목을 바꾸면 그냥 다른 문자열을 넘긴다. */\n  controlled: [],\n  inputs: [\"title\", \"eyebrow\", \"description\", \"size\", \"headingLevel\"],\n  stateAxes: {},\n  web: { roles: [\"heading\"], keyboard: [], focus: \"none\" },\n  native: { roles: [\"header\"], states: [], actions: [] },\n  scenarios: [\n    \"the-title-is-a-real-heading-element-at-the-declared-level-not-styled-text\",\n    \"top-is-body-content-that-scrolls-away-while-topbar-is-fixed-chrome\",\n    \"description-wraps-instead-of-truncating-so-large-text-never-hides-the-question\",\n    \"a-trailing-action-shares-the-title-row-and-drops-below-it-when-space-runs-out\",\n    \"eyebrow-never-carries-information-the-title-does-not-repeat-in-some-form\",\n  ],\n} as const satisfies BehaviorContract;\n"]}
+{"version":3,"file":"top.js","sourceRoot":"","sources":["../src/top.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport { heading, spacing, typography } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * 화면 본문의 **첫 블록**이다. `TopBar`(상단 내비게이션 바)와 다른 자리이고, 그 차이가\n * 이 계약의 존재 이유다.\n *\n * - `TopBar`는 화면에 고정된 크롬이다 — 뒤로가기, 화면 이름, 액션. 스크롤과 무관하게\n *   붙어 있고 safe area를 다룬다.\n * - `Top`은 본문이다 — 스크롤과 함께 올라가고, 사용자가 \"이 화면이 무엇을 묻는지\"\n *   읽는 문장이 여기 있다. 토스 TDS가 \"Top과 ListRow로 화면 대부분을 만든다\"고\n *   말하는 그 Top이고, 지금까지 BurnTok `AppScreenHeader`·Taground `screen-shell`·\n *   Diairy `DetailPanel`이 각자 다시 만들던 블록이다.\n *\n * `Section`과도 다르다. Section은 본문 **중간**의 묶음 제목이라 heading level이 화면\n * 구조에 종속되지만, Top은 화면당 하나뿐인 첫 제목이라 기본이 `h1`이다. 그래서 두\n * 계약을 합치지 않았다 — 합치면 \"이 Section이 화면의 h1인가\"를 매번 물어야 한다.\n */\nexport type TopSize = \"medium\" | \"large\";\n/**\n * `\\n` in the title (2026-10-23). `collapse`(기본): 줄바꿈 문자는 공백이 되고 폭에 따라 자연스럽게 감긴다 — Web이 원래\n * 그렇게 그렸고, Native만 `\\n`을 그대로 그려 두 플랫폼이 달랐다. `preserve`: 제품이 의도한 줄바꿈을 지킨다(히어로 문구).\n * 어느 쪽이든 제목 이름은 한 문장으로 읽힌다 — 줄은 공백 하나로 이어진다. 포트폴리오 사이트 히어로가 `white-space: pre-line`\n * span을 Heading 안에 넣느라 Top을 채택하지 못했다.\n */\nexport type TopTitleLineBreaks = \"collapse\" | \"preserve\";\n\nexport type TopDescriptor = Readonly<{\n  title: string;\n  /** 제목 위 한 줄. 카테고리·단계처럼 제목을 한정하는 짧은 말. */\n  eyebrow?: string;\n  /** 제목 아래 보조 문장. 길면 줄바꿈되며 잘리지 않는다. */\n  description?: string;\n  size?: TopSize;\n  /** 제목 안 `\\n`의 처리. 기본 `collapse`. */\n  titleLineBreaks?: TopTitleLineBreaks;\n  /**\n   * 문서 구조상의 제목 단계. 화면당 하나인 Top은 `1`이 기본이지만, 한 라우트가\n   * 여러 화면을 담는 경우(시트 안의 화면 등) 제품이 낮출 수 있다.\n   */\n  headingLevel?: 1 | 2 | 3;\n}>;\n\nexport const topDefaults = {\n  size: \"large\",\n  headingLevel: 1,\n  titleLineBreaks: \"collapse\",\n} as const satisfies Readonly<{ size: TopSize; headingLevel: 1 | 2 | 3; titleLineBreaks: TopTitleLineBreaks }>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`Top ${field} must not be empty`);\n  }\n}\n\nexport function validateTopDescriptor(descriptor: TopDescriptor): void {\n  if (descriptor === null || typeof descriptor !== \"object\") {\n    throw new TypeError(\"Top descriptor must be an object\");\n  }\n  assertNonEmpty(descriptor.title, \"title\");\n  if (descriptor.eyebrow !== undefined) assertNonEmpty(descriptor.eyebrow, \"eyebrow\");\n  if (descriptor.description !== undefined) {\n    assertNonEmpty(descriptor.description, \"description\");\n  }\n  if (descriptor.size !== undefined && descriptor.size !== \"medium\" && descriptor.size !== \"large\") {\n    throw new TypeError(`Unsupported Top size: ${String(descriptor.size)}`);\n  }\n  if (\n    descriptor.titleLineBreaks !== undefined &&\n    descriptor.titleLineBreaks !== \"collapse\" &&\n    descriptor.titleLineBreaks !== \"preserve\"\n  ) {\n    throw new TypeError(`Unsupported Top titleLineBreaks: ${String(descriptor.titleLineBreaks)}`);\n  }\n  if (\n    descriptor.headingLevel !== undefined &&\n    ![1, 2, 3].includes(descriptor.headingLevel)\n  ) {\n    throw new TypeError(`Unsupported Top headingLevel: ${String(descriptor.headingLevel)}`);\n  }\n}\n\nexport type ResolvedTopTitle = Readonly<{\n  /** Text to draw. `preserve` keeps one `\\n` between trimmed, non-empty lines; `collapse` has none. */\n  text: string;\n  /** The heading's spoken name: the same lines joined by one space, so an intended break never cuts the title. */\n  accessibleName: string;\n  /** Lines as drawn (one entry when collapsed). */\n  lines: readonly string[];\n}>;\n\nexport function resolveTopTitle(descriptor: TopDescriptor): ResolvedTopTitle {\n  validateTopDescriptor(descriptor);\n  const lines = descriptor.title.split(/\\r?\\n/).map((line) => line.trim()).filter((line) => line.length > 0);\n  const accessibleName = lines.join(\" \");\n  const preserve = (descriptor.titleLineBreaks ?? topDefaults.titleLineBreaks) === \"preserve\";\n  return preserve\n    ? { text: lines.join(\"\\n\"), accessibleName, lines }\n    : { text: accessibleName, accessibleName, lines: [accessibleName] };\n}\n\n/**\n * `large`는 화면의 첫 제목, `medium`은 시트·모달 안의 첫 제목이다. 두 단계뿐인 이유는\n * 세 번째가 필요해지는 자리가 곧 `Section`이기 때문이다 — 크기를 더 늘리는 대신 다른\n * 컴포넌트를 쓰라는 신호로 둔다.\n */\nexport const topRecipe = {\n  slots: [\"root\", \"eyebrow\", \"title\", \"description\", \"trailing\"] as const,\n  defaults: { size: topDefaults.size },\n  sizes: {\n    medium: { title: typography.titleLarge, paddingTop: spacing.md, paddingBottom: spacing.sm },\n    // The screen's first title uses the HJM ceiling, `heading.level3` (24). It was `heading.level2` (32) until the\n    // display tier was removed (2026-10-17 user decision, \"글자 너무 커\").\n    large: { title: heading.level3, paddingTop: spacing.xl, paddingBottom: spacing.md },\n  },\n  eyebrow: {\n    color: semanticColors.content.brand,\n    textVariant: \"label\" as const,\n    marginBottom: spacing.xxs,\n  },\n  title: { color: semanticColors.content.primary },\n  description: {\n    color: semanticColors.content.body,\n    textVariant: \"body\" as const,\n    marginTop: spacing.xs,\n  },\n  /** 제목 줄 오른쪽 보조 행동. 본문이므로 TopBar처럼 아이콘 전용을 강제하지 않는다. */\n  trailing: { gap: spacing.xs },\n  gap: spacing.xs,\n} as const satisfies {\n  slots: readonly [\"root\", \"eyebrow\", \"title\", \"description\", \"trailing\"];\n  defaults: { size: TopSize };\n  sizes: Readonly<{\n    medium: { title: typeof typography.titleLarge; paddingTop: number; paddingBottom: number };\n    large: { title: typeof heading.level3; paddingTop: number; paddingBottom: number };\n  }>;\n  eyebrow: { color: ColorReference; textVariant: \"label\"; marginBottom: number };\n  title: { color: ColorReference };\n  description: { color: ColorReference; textVariant: \"body\"; marginTop: number };\n  trailing: { gap: number };\n  gap: number;\n};\n\nexport const topBehavior = {\n  /** 상태 축이 없다 — 화면이 제목을 바꾸면 그냥 다른 문자열을 넘긴다. */\n  controlled: [],\n  inputs: [\"title\", \"eyebrow\", \"description\", \"size\", \"headingLevel\", \"titleLineBreaks\"],\n  stateAxes: {},\n  web: { roles: [\"heading\"], keyboard: [], focus: \"none\" },\n  native: { roles: [\"header\"], states: [], actions: [] },\n  scenarios: [\n    \"the-title-is-a-real-heading-element-at-the-declared-level-not-styled-text\",\n    \"top-is-body-content-that-scrolls-away-while-topbar-is-fixed-chrome\",\n    \"description-wraps-instead-of-truncating-so-large-text-never-hides-the-question\",\n    \"preserved-title-line-breaks-change-only-the-drawing-and-the-heading-name-stays-one-sentence\",\n    \"a-trailing-action-shares-the-title-row-and-drops-below-it-when-space-runs-out\",\n    \"eyebrow-never-carries-information-the-title-does-not-repeat-in-some-form\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Package release shown by documentation surfaces. Kept in sync by a test. */
-export declare const designSystemVersion: "1.41.2";
+export declare const designSystemVersion: "1.43.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Package release shown by documentation surfaces. Kept in sync by a test. */
-export const designSystemVersion = "1.41.2";
+export const designSystemVersion = "1.43.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAiB,CAAC","sourcesContent":["/** Package release shown by documentation surfaces. Kept in sync by a test. */\nexport const designSystemVersion = \"1.41.2\" as const;\n"]}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAiB,CAAC","sourcesContent":["/** Package release shown by documentation surfaces. Kept in sync by a test. */\nexport const designSystemVersion = \"1.43.0\" as const;\n"]}

package/docs/affix.md

@@ -25,3 +25,10 @@ CSS sticky의 기준을 바꾼다. 부모 자체가 콘텐츠와 같은 높이
 계약: [affix.ts](../src/affix.ts). UI: [renderer](../../react/src/affix.tsx).
 사용 예제: [Web additions](../../../showcase/web/src/patterns/WebAdditions.stories.tsx).
 검증: [브라우저 스크롤·초점 회귀](../../react/test/web-additions.browser.test.tsx).
+
+## 쌓임과 바탕 (2026-10-23, 개발 소스·미게시)
+
+`layer`(`sticky` 기본 · `base`)는 공통 `layer` 단계에서 고르고, `fill`(`canvas` 기본 · `none`)은 상자 뒤 바탕이다.
+기본값은 `affixRecipe.defaults`가 소유한다. 이전에는 z-index가 없어 뒤에 오는 position 지정 콘텐츠가 고정된 상자 위로 그려졌다.
+상자는 언제나 sticky 또는 relative라 고정·해제 상태 모두 같은 쌓임을 가진다. 숫자 z-index는 받지 않는다 —
+dropdown·modal 단계보다 위로 올라가면 메뉴와 대화상자를 가리기 때문이다. 근거와 사용법은 [사용 지침](usage/components/affix.md).

package/docs/avatar-fallback.md

@@ -79,3 +79,22 @@ or exhaustive geometry and screen-reader behavior.
 the last word, counted in code points. Web had taken the first two words and Native the first and last, so "Kim Min Jun"
 read "KM" on Web and "KJ" on Native; Native also split surrogate pairs. First+last was kept because it shows the family and
 given names instead of a middle name. Native `initials` still overrides (at most three code points).
+
+## Presentation axes (2026-10-23)
+
+Burntok's `UserAvatar` (about 70 call sites, 22/28/32/44, transparent circle filled by a generated SVG) and
+Yajalal's `PlayerAvatar` (rounded square with a team badge on the corner) could not adopt Avatar: `name` was
+required, Web had no image host, Web had four sizes, Native threw below 24, and the frame always drew a background
+and a 1px border. The axes now live in `avatarRecipe`:
+
+- `size`: named steps `xxsmall` 22 · `xsmall` 28 · `small` 32 · `medium` 40 · `touch` 44 · `large` 48 · `xlarge` 64
+  (`resolveAvatarSize`). Native keeps numeric points for existing callers; the floor is the smallest step (22),
+  where the label-size initials still fit.
+- `decorative`: hides the whole avatar and makes `name` optional. A meaningful avatar still requires `name`
+  (Web) or `name` + `accessibilityLabel` (Native).
+- `frame`: `outlined` (default, unchanged) · `surface` · `none`.
+- `shape`: `circle` · `rounded` on both renderers (Native was circle only).
+- `accessory` + `accessoryPlacement` (`bottom-end` default · `top-end`): a non-interactive corner mark outside the
+  clipping frame, on the avatar's box corner (`avatarRecipe.accessory.offset` 0; offsets are outward overhangs as in
+  Asset and IconTile). IconTile uses the same placement names.
+- Web `renderImage`: product image host with a generation-guarded `onError`, exclusive with `imageProps`.

package/docs/brand-boundary.md

@@ -1,6 +1,6 @@
 # 브랜드 경계 — 제품이 바꿀 수 있는 것과 그 경로
 
-상태: 규범 · 검토일: 2026-10-20 · 이 문서가 브랜드·테마 주입 규칙의 단일 원본이다.
+상태: 규범 · 검토일: 2026-10-23 · 이 문서가 브랜드·테마 주입 규칙의 단일 원본이다.
 [theming.md](./theming.md)는 사용법 예시, [consumer-policy.md](./consumer-policy.md)는 채택 정책,
 [design-system-provider.md](./design-system-provider.md)는 환경 축 설계를 다루며 브랜드 규칙은 여기로 링크한다.
 
@@ -32,6 +32,21 @@ CSS 변수 재정의, 제품 자체 토큰 생성기)였고, 문서 세 개가
 
 안전 영역 등 환경을 연결하는 `value={resolvedValue}` 중첩 Provider도 현재 모드의 해석된 브랜드 팔레트를 하위 Provider에 전달한다. 명시적으로 새 `brandPalette`를 지정하면 기존처럼 그 범위를 대체한다. 이 구분은 환경 bridge 뒤의 일반 Provider가 브랜드색을 기본값으로 되돌리던 문제를 막는다.
 
+### 1.1 하위 범위의 일부 역할만 바꾸기 — `brandPaletteMode` (개발 소스·미게시)
+
+중첩 Provider의 `brandPaletteMode`는 하위 `brandPalette`와 상위 팔레트의 관계를 정한다.
+
+| 값 | 결과 | 쓰는 곳 |
+| --- | --- | --- |
+| `replace`(기본) | HJM 기본값(또는 프로필) 위에 하위가 넘긴 역할만 놓는다. 상위 브랜드는 이 범위에서 끊긴다 | 다른 브랜드의 임베드처럼 상위 색을 물려받지 않아야 하는 범위 |
+| `extend` | theme별로 상위 팔레트 위에 하위가 넘긴 역할만 덮는다. 더 깊은 `extend`도 차례로 쌓인다 | 종이·바다처럼 바탕·표면 몇 역할만 바꾸고 제품 브랜드는 유지하는 범위 |
+
+`brandPalette` 없이 준 모드는 효과가 없다. `value` 중첩 Provider와는 함께 쓸 수 없다(타입이 막는다).
+기존 `replace` 기본값은 바꾸지 않는다. 기본을 `extend`로 바꾸면 지금 상위 색을 끊으려고 `brandPalette`를 다시 준
+범위가 조용히 상위 색을 물려받게 되기 때문이다. 결정 근거: 2026-10-23 번뚝 웹·앱 ThemeProvider는 상위 덮어쓰기를
+직접 누적했고(`apps/web/src/components/ThemeProvider.tsx` `BrandPaletteScope`), 다에리 앱은 `shoreBrandPaletteWith()`로
+기본 팔레트를 매번 다시 합쳤다. 병합 규칙은 contracts `resolveProviderBrandPalette(inherited, supplied, value, mode)`가 소유한다.
+
 ## 2. 모든 브랜드 팔레트는 대비 검사를 통과해야 한다
 
 `@hjmds/design-contracts/palette-contrast`의 `checkBrandPaletteContrast(brandPalette)`가 Provider와 같은 방식으로
@@ -98,5 +113,12 @@ HJM: semantic color role과 light/dark 대비, spacing·type scale·radius·moti
 키보드·screen-reader 행동, loading·empty·error·disabled·focus 문법.
 
 제품: 이름·로고·대표 이미지, 검증한 `designProfile` 데이터와 `brandPalette`로 표현한 브랜드 색, 도메인 상태 → `AccentTone` 매핑, 콘텐츠 밀도와
-정보 우선순위, copy·i18n·내비게이션 구조. 제품 고유 gradient는 light/dark·on-color 대비와 reduce-motion을 제품 테스트로
+정보 우선순위, copy·i18n·내비게이션 구조.
+
+### 제품 분류 색(Badge `categoryColor`) — 개발 소스, 미게시
+
+경기 시리즈·계약 등급처럼 상태(`AccentTone`)도 브랜드도 아닌 **제품 분류**는 Badge의 `categoryColor`(테마별 6자리 hex)로 넣는다.
+분류의 색 정의는 제품이, 틀·글자·간격과 글자색 선택은 HJM이 소유한다. HJM은 `resolveBadgeCategoryColor`(`@hjmds/design-contracts/recipes`)로
+테마마다 채움 위 글자 또는 outline 글자의 대비를 계산하고 4.5:1 미만이면 렌더 전에 던진다. 배지 하나를 `brandPalette` Provider로
+감싸 분류색을 칠하지 않는다 — 그 범위의 primary·contentBrand 등이 함께 바뀌는 브랜드 경로의 오용이다(2026-10-23 야잘알 GameSeriesBadge·FaCards 감사). 제품 고유 gradient는 light/dark·on-color 대비와 reduce-motion을 제품 테스트로
 검증한다([consumer-policy.md §4](./consumer-policy.md#4-제품-정체성-경계)).

package/docs/chart.md

@@ -204,3 +204,10 @@ reduced motion은 즉시 교체하고, background는 새 표현에 정착하며,
 `LineChart.scrubEmphasis="before" | "after"`는 현재 포커스의 x에서 클립을 나누어 선택한
 쪽을 계열 색으로, 나머지를 축 레이블 색으로 표시한다. 새로운 점·수치·추천을 계산하지
 않으며 기존 드래그·키보드·접근성 포커스와 `holdOnRelease`를 그대로 사용한다.
+
+## 범례 배치 (2026-10-23, 개발 소스·미게시)
+
+`ChartLegend.layout`은 `stack`(계열마다 한 행)과 `inline`(한 줄로 흐르고 감김) 두 값이다. 견본 10·모서리 3, 견본·이름·값 사이
+`spacing.xs`, inline 항목 사이 `spacing.md`·줄 사이 `spacing.xxs`, stack 행 최소 32, 선택 밖 흐림 0.5는 `chartRecipe.legend`가 소유한다.
+선택의창 지도 범례가 Native의 세로 고정 때문에 ChartLegend를 채택하지 못한 것이 계기다(사용 지침 [Chart](usage/components/chart.md)).
+기본값은 기존 동작을 유지한다: Web은 선택 버튼(`onSelect`)이 없으면 `inline`, 있으면 `stack`, Native는 `stack`.

package/docs/collection-rail.md

@@ -33,7 +33,10 @@ Native row만 RTL에서 역방향으로 배치하며 데이터/React key/읽기
 
 ## 배치와 플랫폼 경계
 
-comfortable 최대 폭360은 `layout.readingMaxWidth / 2`, compact240은 `/3`이다. 실제 폭은 viewport와
+comfortable 최대 폭360은 `layout.readingMaxWidth / 2`, compact240은 `/3`, chip144는 `/5`다(2026-10-23 추가).
+간격은 `gapSteps`의 spacing 단계로 카드 밀도는 `md`16, chip은 `xs`8이다. 야잘알 홈의 145pt 미니 스코어보드 줄이
+카드 폭(240+)을 강제받아 원시 ScrollView를 쓰던 문제다. 내용 폭 항목(`itemWidth="content"`)은 넣지 않았다 —
+이전/다음·앞쪽 anchor·초점 노출이 모두 한 항목 폭(stride) 단위의 geometry이고, 실제 소비처의 칩도 같은 폭이다. 실제 폭은 viewport와
 `spacing.xl`24 hint를 함께 고려한다. 간격 `spacing.md`16을 유지하므로 viewport358에서 카드334와 다음 카드8이 노출된다.
 뷰포트24 이하에서는 peek보다 내용 폭을 우선한다. 길고 많은 데이터는 VirtualList/제품별 가상화 계약을 사용한다.
 브랜드 색·표면·폰트·카드 경계는 Provider와 Card가 소유한다. 가로 탐색을 테마의 미지원 screen/composition 축에 자동 연결하지 않는다.

package/docs/generated/component-maturity.md

@@ -1,6 +1,6 @@
 # Component maturity and evidence manifest
 
-> Generated from `@hjmds/design-contracts` 1.41.2. Do not edit this file directly; run `pnpm contracts:sync`.
+> Generated from `@hjmds/design-contracts` 1.43.0. Do not edit this file directly; run `pnpm contracts:sync`.
 
 This document is the human-readable projection of the same catalog and Showcase manifest consumed by product CI.
 

package/docs/generated/renderer-evidence.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "designSystemVersion": "1.41.2",
+  "designSystemVersion": "1.43.0",
   "source": "packages/design-contracts/docs/generated/showcase-manifest.json",
   "surfaces": {
     "web": {
       "packageName": "@hjmds/react",
-      "packageVersion": "1.41.2",
+      "packageVersion": "1.43.0",
       "activeComponents": 131,
       "claimedComponents": 131,
       "completeScenarioComponents": 130,
@@ -830,7 +830,8 @@
           "claimed": true,
           "subpath": "./actions",
           "exportNames": [
-            "IconButton"
+            "IconButton",
+            "IconButtonLink"
           ],
           "proofs": [
             {
@@ -7062,7 +7063,7 @@
     },
     "native": {
       "packageName": "@hjmds/react-native",
-      "packageVersion": "1.41.2",
+      "packageVersion": "1.43.0",
       "activeComponents": 113,
       "claimedComponents": 113,
       "completeScenarioComponents": 110,
@@ -7768,7 +7769,8 @@
           "claimed": true,
           "subpath": "./bottom-cta",
           "exportNames": [
-            "IconButton"
+            "IconButton",
+            "IconButtonLink"
           ],
           "proofs": [
             {
@@ -11868,7 +11870,9 @@
           "claimed": true,
           "subpath": "./screens",
           "exportNames": [
-            "ScreenLayout"
+            "ScreenLayout",
+            "ScreenHost",
+            "ScreenRefreshControl"
           ],
           "proofs": [
             {

package/docs/generated/renderer-evidence.md

@@ -1,6 +1,6 @@
 # Renderer evidence coverage
 
-> Generated for HJM 1.41.2. Do not edit directly; run `pnpm evidence:sync`.
+> Generated for HJM 1.43.0. Do not edit directly; run `pnpm evidence:sync`.
 
 This projection joins the canonical surface maturity manifest with first-party renderer claims. Missing scenarios are explicit beta promotion debt; stable surfaces are blocked by CI until none remain.
 

package/docs/generated/showcase-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "designSystemVersion": "1.41.2",
+  "designSystemVersion": "1.43.0",
   "packageName": "@hjmds/design-contracts",
   "components": [
     {
@@ -809,7 +809,8 @@
       "name": "IconButton",
       "label": "아이콘 버튼",
       "companions": [
-        "ClipboardIconButton"
+        "ClipboardIconButton",
+        "IconButtonLink"
       ],
       "extensions": [
         "NotificationBell"
@@ -4228,7 +4229,8 @@
       "companions": [],
       "extensions": [
         "GridReveal",
-        "ImageViewer"
+        "ImageViewer",
+        "ImageViewerTrigger"
       ],
       "category": "data-display",
       "platform": "shared",
@@ -4976,7 +4978,9 @@
       "storyId": "overlay/alert-dialog",
       "name": "AlertDialog",
       "label": "확인 대화상자",
-      "companions": [],
+      "companions": [
+        "AlertDialogQueueProvider"
+      ],
       "extensions": [],
       "category": "overlay",
       "platform": "adaptive",
@@ -5414,7 +5418,10 @@
       "storyId": "layout/screen-layout",
       "name": "ScreenLayout",
       "label": "화면 골격",
-      "companions": [],
+      "companions": [
+        "ScreenHost",
+        "ScreenRefreshControl"
+      ],
       "extensions": [],
       "category": "layout",
       "platform": "adaptive",

package/docs/image.md

@@ -77,6 +77,11 @@ Dialog·Sheet가 이미 소유한 문제입니다. 이 조합을 Image 자체에
 필요해지면 별도 Web 전용 `ImagePreview` overlay가 기존 `Dialog`/`AnchoredOverlay` 계약을
 조합해서 풀 문제이지, `Image`가 escape hatch로 열 문제가 아닙니다.
 
+2026-10-23: 같은 이유로 "누르면 크게 보기"의 트리거도 `Image` prop이 아니라 뷰어 쪽 `ImageViewerTrigger`
+(`/image-viewer`)에 둡니다. 포트폴리오 사이트와 Spint가 사진을 원시 button·Pressable로 감싸 이름·포커스 링·
+커서를 각자 정하던 우회를 대신합니다. 트리거는 button 의미와 `imageViewerTriggerRecipe`(액자 `radius.md`,
+`zoom-in` 커서, 눌림·비활성 투명도)를 소유하고, 뷰어의 `open` 수명주기는 여전히 `ImageViewer`와 제품이 가집니다.
+
 ## 플랫폼 번역
 
 `fit: cover | contain | fill`은 Web `object-fit`과 거의 그대로 대응합니다. RN

package/docs/list-row.md

@@ -12,3 +12,11 @@
   주면 된다.
 - 로딩 행은 상호작용하지 않는다 — 아직 활성화할 것이 없다.
 - `role="status"` + `aria-busy`로 알리고, 문구(`loadingLabel`)는 제품이 현지화한다.
+
+## trailing accessory (2026-10-23, 개발 소스·미게시)
+
+`trailingAccessory="disclosure"`는 행이 다른 화면으로 이동한다는 의미 축이다. 모양(`chevronEnd`·`glyph.sm`·`content.decorative`·Icon `regular`)과
+간격(trailing 값 뒤 `spacing.xs`)은 `listRowRecipe.accessories`가, 순서(content → trailing → accessory → `trailingAction`)는 두 renderer가 같게 지킨다.
+장식이라 Web은 `aria-hidden`, Native는 보조기기에서 숨기며 행 이름에 더하지 않는다. RTL에서는 읽기 방향 끝을 가리킨다.
+기존 API로는 `trailing`에 Icon을 넣는 방법뿐이었고, 제품마다 크기·색·RTL·값과의 간격이 달라졌다(야잘알 10·유틸버스 24·spint 3곳 감사).
+사용법은 [사용 지침](usage/components/list-row.md)을 따른다.

package/docs/optional-adapters.md

@@ -97,6 +97,9 @@ Expo Go cannot verify these linked native modules.
   paging without a swipe, and unmounts on close to reset its session. Failed images offer retry.
   Host-provided safe-area insets are required when placing it edge-to-edge. Remote image permission,
   URL lifetime and caching remain product responsibilities; the adapter does not fetch metadata.
+- ImageViewerTrigger (same subpath, 2026-10-23) is the button around product media that opens the viewer:
+  localized `label`, image-frame focus ring, zoom cursor and pressed opacity from `imageViewerTriggerRecipe`.
+  The product still owns `open`; the trigger adds no gesture code of its own.
 - KeyboardDock translates with the keyboard. `clearance` is an additional nonnegative gap above it;
   the host retains bottom safe-area ownership. Do not combine this with another keyboard avoidance
   wrapper around the same content. KeyboardFormScrollView handles focused form fields.

package/docs/overlay-stack.md

@@ -22,3 +22,30 @@ openSheet({ … });      // 그 다음에 다음 표면을 연다
 
 **타이머가 사라진다.** `closed`는 Dialog/Sheet의 `onDismissComplete`에서 resolve되므로
 제품이 0ms 타이머로 정리 시점을 추측할 필요가 없다.
+
+## 결과를 돌려주는 확인 대기열 — `AlertDialogQueueProvider` (2026-10-23, 개발 소스·미게시)
+
+번뚝 웹 `components/ui/AppDialog.tsx`(321줄)와 앱 `AppDialog.tsx`(293줄)가 AlertDialog 둘레에 같은 것을 각자 만들었다.
+결과 Promise, async confirm(처리 중 유지·실패 시 열린 채 오류), FIFO 대기열, 포커스 복귀, route scope, blocking 우선순위다.
+위의 `useDialog`/`useSheet`는 Dialog·Sheet만 받고 두 번째 열기를 거부하며 RN에는 이 층이 없었다. 확인 질문은 다른 확인이 떠 있을 때
+도착하는 것이 정상이므로 "한 번에 하나"를 거부가 아니라 **순서 대기**로 지키는 별도 공급자를 둔다.
+
+| 소유 | 위치 |
+| --- | --- |
+| 순서·결과 1회 확정·scope 정리 | contracts `createAlertDialogQueue`(`components/alert-dialog`). `enqueue → Promise<AlertDialogResult>`, `settle`은 맨 앞 항목만, `retainScope`가 다른 scope 항목을 `interrupted`로, `setActive(false)`가 전부와 이후 요청을 `interrupted`로 끝낸다 |
+| 한 대화상자의 확인·처리 중·실패 | 기존 `createAlertDialogSession`(AlertDialog). `request.onConfirm`이 Promise면 처리 중 닫힘을 막고, 거부되면 열린 채 오류를 보이며 Promise는 성공할 때까지 기다린다 |
+| 화면 표시 | Web·Native `AlertDialogQueueProvider` + `useAlertDialogQueue().open(request, options?)` (`/alert-dialog-queue`) |
+
+- **결과:** Web은 AlertDialog `onOpenChange(false, reason)`의 사유로(`confirm` → confirmed, 나머지 → cancelled 사유), Native는 native 닫힘 뒤 `onResult`로 확정한다.
+  그래서 Native는 앞 대화상자가 사라진 뒤에 다음 대화상자를 띄운다.
+- **scope:** 공급자 `scope`(보통 route)가 바뀌면 다른 scope의 질문은 화면에서 내려가고 `interrupted`가 된다. `open`은 호출 컴포넌트가 렌더된 scope에 묶이므로
+  떠난 화면의 늦은 콜백도 다음 화면에 질문을 띄우지 못한다. 공급자가 사라지면 남은 질문과 이후 요청이 모두 `interrupted`다.
+- **포커스(Web):** 질문 묶음이 시작될 때 초점이 있던 요소를 기억해 묶음의 모든 대화상자가 그곳으로 돌려준다. 두 번째 대화상자가 지워진 첫 대화상자의 버튼으로 돌아가지 않는다.
+  결과는 renderer 갱신보다 먼저 resolve되므로 `await open()` 바로 뒤에 다시 켠 trigger에 초점이 돌아간다. 대화상자가 떠 있는 동안 배경은 이미 inert이므로
+  호출부가 trigger를 따로 disabled로 두지 않는다(번뚝은 disabled trigger 때문에 0ms 뒤 초점 재시도를 붙였다). 작업까지 기다릴 때는 `request.onConfirm`에 둔다.
+- **우선순위(Web):** 공급자 `modalPriority`(기본 0)로 대기열 대화상자의 층을 정한다. 필수 gate는 더 높은 `modalPriority`의 모달로 두면 위에서 입력을 받고,
+  대기열 대화상자는 그 아래에서 inert로 기다린다. 제품 DOM 감시로 대기열을 멈추지 않는다. Native AlertDialog에는 우선순위 축이 없어 제공하지 않는다.
+- **StrictMode(Web AlertDialog 수정):** 열린 채 마운트한 AlertDialog는 StrictMode의 모의 unmount가 render 중 만든 세션을 interrupt해 확인·취소가 되지 않았다.
+  재마운트 때 interrupt된 세션을 새로 만든다. 번뚝은 이를 피하려고 열기를 한 task 미뤘다.
+- 아이콘(Web `icon`)·크기(`size`)는 요청별 `options`, Native 초점 복귀는 `options.returnFocusRef`로 넘긴다. 문구·행동은 `AlertDialogRequest`가 그대로 소유한다.
+

package/docs/screen-patterns.md

@@ -44,7 +44,9 @@ Flutter 앱에는 React 컴포넌트를 주입할 수 없다. 화면 역할과
   저장 방식·낙관적 갱신·실패 복구·탈퇴 확인은 [action-session](action-session.md)과 제품이 소유한다.
 - `NotificationInboxScreen`: 필터는 상태가 바뀌어도 유지하고 본문만 교체한다. `NotificationItem`은
   기존 ListRow에 지역화한 읽음 상태와 시각을 조합한다. href/onClick(Web), onPress(Native)를
-  그대로 사용하며 표시·탭·스크롤 자체가 읽음 처리를 실행하지 않는다.
+  그대로 사용하며 표시·탭·스크롤 자체가 읽음 처리를 실행하지 않는다. `unreadLabel`을 주면 안 읽음 항목에
+  NotificationRow와 같은 점(`notificationRowRecipe.unreadSize`, content brand)을 이름과 함께 그린다(2026-10-23,
+  Spint가 `trailing`에 "•" 글자를 두던 우회). Native 누르는 행의 합성 이름에 상태·시각 줄과 안 읽음 이름을 포함한다.
 - `ChatMessage`: 발신/수신 정렬, 작성자, 아바타, 답장 인용, 전송 상태와 시각을 합성한다.
   기존 Asset/VoiceNote 등은 children에 넣고 영수증·반응·재시도는 제품이 넘긴다. 전체 타임라인을
   live region으로 만들지 않으므로 과거 메시지 로딩 때 읽기 순서를 가로채지 않는다.
@@ -158,7 +160,7 @@ UploadItem, RadioGroup, AlertDialog, TextField와 ScreenLayout의 계약을 그
 | ModerationScreen | 사유 선택, 신고 활성 조건, 차단 확인 | 서버 신고/권한, 차단 mutation |
 | MediaSelectionScreen | 썸네일 격자, 업로드 상태, 순서/삭제/재시도, 제품 작업 중 순서·회전·삭제 잠금(`disabled`, 1.32.0) | 실제 picker, 권한, 이미지 URI 수명, 업로드, 잠글 작업의 시작·끝 |
 | SearchScreen | 300ms debounce, 이전 요청 AbortSignal, 검색/필터 슬롯, 기본 입력의 확정 신호(`onSubmit`)·검색 중 표시(`searching`)·label 숨김, 한 줄 가로 스크롤 필터 줄, 두 단계 검색 단계(검색 전·입력 중·결과)와 확정 경로, 최근·추천 검색어·제안 배치, 결과 개수·정렬, 적용 필터 칩, 초안/적용 필터 시트, 0건 원인별 복구, 개수 낭독 | API, 제안·결과·개수 조회, 오류 문구, 필터 정의와 계산, 정렬 값, 최근 검색 저장소, 늦은 응답 무시 |
-| PermissionScreen | prompt/denied/granted/unavailable에 맞는 action | OS 요청과 설정 이동, 앱 복귀 후 실제 권한 조회 |
+| PermissionScreen | prompt/denied/granted/unavailable에 맞는 action, footer 순서 primary → recheck(denied) → alternative(granted 전) → skip(`resolvePermissionFooter`, 2026-10-23) | OS 요청과 설정 이동, 앱 복귀 후 실제 권한 조회, 대체 경로 실행 |
 | OnboardingScreen | 단계 범위 검증, 이전/다음/건너뛰기 | 선택 데이터와 완료 여부 저장 |
 | CommentThreadScreen | 부모/답글, 펼침, 좋아요/답글, 작성창 | 실제 댓글/권한/전송과 성공 후 초안 정리 |
 
@@ -474,9 +476,44 @@ HJM 1.31.0 채택 뒤에도 제품이 공통 계산을 다시 하던 세 지점
 - `IconTile.icon`은 함수도 받는다. 함수는 `IconTileArtwork`(`{ edge }`: `fixed`는 64, `fill`은 측정한 칸 크기)를 받아
   고정 크기 이미지가 스스로 크기를 맞춘다. 측정 전 추정이 필요한 host는 `resolveIconTileFillEdge(cellWidth)`로
   같은 48~68 제한을 쓴다. 유틸버스 런처가 이 제한을 격자 폭에서 다시 계산해 아트워크 크기로 넘겼다.
+- `IconTile` `locked`·`lockedLabel`·`accessory`·`accessoryPlacement`(2026-10-23): 눌러서 이유를 보는 잠금 상태와 틀 모서리
+  표식을 HJM이 소유한다. 잠금은 틀·제목만 `iconTileRecipe.locked.opacity`로 흐리고 표식은 그대로 두며, 표식은
+  `iconTileRecipe.accessory.offset` 4만큼 바깥으로 나간다(Asset·Avatar와 같은 뜻의 offset, 모서리 이름 `CornerAccessoryPlacement`).
+  유틸버스 ToolboxScreen이 바깥 View에 `activation.disabledOpacity`를 주고 배지를 `right: -4, top: -4`에 놓던 우회를 대신한다.
 - `BottomNavigationInsetProvider`의 덮인 높이는 ScreenLayout만 적용한다(patch). 사용 지침이 `scroll="content"` 화면에
   `useBottomNavigationInset()`을 다시 더하라고 안내해, 따르면 마지막 영역 여백과 목록 여백이 두 번 쌓였다. 코드는
   이미 한 곳(마지막 영역)만 적용했으므로 지침을 고치고 두 renderer에 한 번만 적용되는지 검사를 더했다.
 
 검증: Web `hjm-1320-screen-insets.browser.test.tsx`(Chromium), Native `hjm-1320-screen-insets.test.tsx`(host 렌더),
 contracts `screen-patterns.test.ts`. 실기기·npm 게시·소비 앱 반영을 뜻하지 않는다.
+
+## 2026-10-23 화면 바깥 host — Native `ScreenHost` (개발 소스·미게시)
+
+선택의창 `app/_layout.tsx` AppCanvas, Unairplane `ui/index.tsx` AppScreenHost·`FlightLookupScreen`·`BoardingPassScannerScreen`이
+같은 `SafeAreaView edges={["top","left","right"]}` + `colors.bg` 칠하기를 반복했다. ScreenLayout(Native)은 `safeAreaTop`·`safeAreaBottom`
+숫자만 받고 좌우 inset이 없으며, 루트가 읽기 폭(720)에서 멈춰 그 밖과 노치 아래에 창 배경이 드러났기 때문이다.
+여러 화면·navigator 전체를 감싸는 자리라 ScreenLayout prop이 아니라 바깥 host로 둔다.
+
+- `ScreenHost`(`@hjmds/react-native/screens`, ScreenLayout companion): 창 전체를 차지하고 `surface="default"`이면 theme `bg`를 칠한다.
+  `edges`(기본 `screenHostDefaults.edges` = top·right·left)만큼 HjmNativeProvider `safeAreaInsets`를 padding으로 준다.
+  값과 검증은 contracts `resolveScreenHostInsets`(알 수 없는·중복 edge는 TypeError, 음수 inset은 RangeError)가 소유한다.
+- 아래는 기본에서 뺀다. ScreenLayout `safeAreaBottom`이 마지막 영역에 max(16, inset)을 한 번 주므로 host가 아래를 들이면 16 + inset이 된다.
+  ScreenLayout·footer가 없는 내용을 감쌀 때만 `bottom`을 넣는다.
+- Web은 만들지 않는다. HjmProvider `host="surface"`가 문서 바탕을 칠하고 각 고정 영역이 `env(safe-area-inset-*)`를 직접 쓰므로
+  같은 공백(창 배경 노출·좌우 inset 누락)이 없다.
+
+## 2026-10-23 당겨서 새로고침 — Native ScreenLayout `onRefresh` (개발 소스·미게시)
+
+spint 홈·알림·셀 세 화면이 `RefreshControl tintColor="transparent" colors={["transparent"]}`로 시스템 스피너를 숨기고
+목록 머리에 FlowerSpinner를 직접 넣었다. ScreenLayout(Native)은 `scrollProps.refreshControl`을 그대로 넘길 뿐 새로고침 상태와
+제품 표시 자리가 없었기 때문이다.
+
+- ScreenLayout `onRefresh`·`refreshing`(기본 false)·`refreshLabel`: 화면이 당김 동작과 표시를 소유한다. `scroll="screen"`(그리고 상태 교체 중의
+  본문)은 ScreenLayout의 ScrollView에 붙인다. `scroll="content"` 목록은 그 목록 안에서 `ScreenRefreshControl`을 `refreshControl`로 넘기며,
+  상태·색·표시는 감싸는 ScreenLayout context에서 읽는다(밖에서 쓰면 TypeError).
+- 표시: 기존 `loadingIndicator` 슬롯을 그대로 쓴다. 있으면 시스템 컨트롤은 제스처와 iOS 상단 공간을 위해 남기되 투명하게 그리고,
+  제품 표시를 본문 위쪽 `screenPatternRecipe.refresh.indicatorOffset`(16) 아래 가운데에 `refreshing` 동안 띄운다. 입력을 막지 않으며
+  보조기술에는 `refreshLabel` 이름의 busy progressbar로 알린다. 없으면 시스템 스피너가 `refresh.tint`(spinner brand)·`refresh.background`(surface)로 돈다.
+- `pullToDismiss`와 함께 쓰지 않는다(같은 맨 위 아래 당김). `scrollProps.refreshControl`과도 같이 주지 않는다(소유자 하나).
+- Web은 만들지 않는다. 브라우저 기본 당김(overscroll)이 있고 HJM Web에 당김 제스처 계약이 없어 같은 반복이 확인되지 않았다.
+

package/docs/sidebar.md

@@ -43,3 +43,18 @@
 2026-10-07 소비 감사에서 Web 항목의 숫자 recipe 모서리가 프로필을 우회했다. 기존 `radius.md` 역할을 가까운 Provider의 CSS 변수로 읽고 변수 없는 독립 사용은 recipe 12를 유지한다. 레일 폭·링크·현재 위치·접기·초점과 Web 전용 범위는 바꾸지 않는다.
 
 프로필 연결은 1.15.0 이후 미게시 변경이며, 기본 배포 계약과 실제 Native 기기 검증은 구분한다.
+
+## 라우터 링크 어댑터와 폭 단계 (2026-10-23, 개발 소스·미게시)
+
+**`renderLink`.** 항목은 순수 `<a href>`였고 `onNavigate`는 알림이라 기본 이동을 막지 못했다. 그래서 Next 같은
+client router를 쓰는 제품은 항목마다 문서 전체를 다시 불러오게 되어 Sidebar를 채택하지 못하고 자체 nav를 유지했다
+(다에리 웹 `WebShell` ProductNav). `BottomNavigation.renderLink`와 같은 계약으로 제품이 항목 링크를 그린다.
+HJM은 `href`·`className`·`aria-current`·접힘 `aria-label`·`onClick`(비활성 차단·bounce·`onNavigate`)·내용을 준비하고
+어댑터는 그 props를 자기 링크에 그대로 펼친다. 비활성 항목과 `destination` 없는 항목은 어댑터를 거치지 않는다 —
+죽은 링크가 router로 넘어가 이동하는 일을 막는다. 단일 앵커 컴포넌트(`Link`·`ButtonLink`)의 `renderAnchor`가 아니라
+탐색 묶음(BottomNavigation·Card·ListRow)의 `renderLink` 이름을 따른다.
+
+**`size`.** 펼친 폭은 `regular` 260(기본)과 `compact` 220 두 단계다(`sidebarRecipe.sizes`). 그룹 제목과 긴 라벨이 있는
+관리·문서 목록은 regular, 그룹 없이 짧은 라벨 3~5개를 두는 제품 셸 rail은 compact다. 다에리 rail이 220이었다.
+임의 px를 받지 않는 이유는 폭이 라벨 줄바꿈·배지 위치와 함께 정해지는 recipe 값이기 때문이다. 접힌 폭 72는 두 단계 모두 같다.
+`widths.expanded`(260)는 1.12부터 recipe를 읽던 소비자를 위해 regular 값으로 남긴다.