@ihabdevteam/core 0.170.0 → 0.171.0

package/dist/ihabdevteam-core.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react';
+import { ComponentType } from 'react';
 import { Context } from 'react';
 import { CSSProperties } from 'react';
 import { Dispatch } from 'react';
@@ -10,6 +10,7 @@ import { ForwardRefExoticComponent } from 'react';
 import type { HTMLAttributes } from 'react';
 import { JSX } from 'react';
 import { KeyboardEvent as KeyboardEvent_2 } from 'react';
+import { LazyExoticComponent } from 'react';
 import { MouseEvent as MouseEvent_2 } from 'react';
 import { default as React_2 } from 'react';
 import * as React_3 from 'react';
@@ -1555,7 +1556,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.170.0";
+export declare const CORE_VERSION = "0.171.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -3013,6 +3014,29 @@ export declare interface LandingHeaderProps {
     };
 }
 
+/**
+ * 화면을 늦게 받아 오는 자리 — `lazy()` 를 그냥 쓰지 않고 이걸 쓴다.
+ *
+ * 맨 `lazy(() => import(…))` 는 **모듈이 undefined 로 와도 그대로 `.default` 를 읽는다.**
+ * 그 일이 실제로 난다: 배포 skew 복구가 `vite:preloadError` 를 `preventDefault()` 하면
+ * Vite 헬퍼의 `catch` 가 아무것도 안 던지고 undefined 로 resolve 한다(자세한 것은
+ * `chunkSkew.ts`). 그러면 새로고침이 이미 걸려 있는데도 그 틈에 React 가
+ * `undefined.default` 를 읽어 **오류 화면이 한 번 뜨고 가짜 보고가 남는다.**
+ *
+ * 두 가지를 한다.
+ *  1. **새로고침이 예약돼 있으면 아무것도 결정하지 않는다** — 영영 resolve 하지 않는
+ *     약속을 돌려 Suspense 를 그대로 둔다. 곧 새 판이 뜬다.
+ *  2. 그게 아닌데 모듈이 이상하면 **어느 화면인지 적어** 던진다. 지금까지 이 오류는
+ *     스택이 통째로 vendor-react 안이라(minify 된 `q`) 어느 화면에서 났는지 알 수 없었다.
+ *
+ * Vite 가 아닌 번들러(Next 등)에서는 `vite:preloadError` 가 오지 않으니 이 감싸개는
+ * "모듈이 이상하면 어느 화면인지 적어 던진다" 만 한다 — 그것만으로도 맨 `lazy` 보다 낫다.
+ * @public
+ */
+export declare function lazyPage<T extends ComponentType<any>>(name: string, load: () => Promise<{
+    default: T;
+} | undefined>): LazyExoticComponent<T>;
+
 declare type LeaderboardFn = (gameKey: string, limit?: number) => Promise<LeaderboardRow[] | null>;
 
 /**
@@ -5029,6 +5053,44 @@ export declare interface Recommendation {
  */
 export declare function recommendTables(tables: readonly TableCandidate[], weakLabels: readonly string[], limit?: number): Recommendation[];
 
+/**
+ * 배포 skew 복구 — 그리고 그 복구가 내던 오류 화면.
+ *
+ * ── 무엇이 문제였나 ──
+ * 새 배포로 청크 해시가 바뀌면 캐시된 옛 index.html 이 사라진 청크를 부른다. Vite 는
+ * `vite:preloadError` 를 던지고, 우리는 그때 한 번 새로고침해 새 index.html 을 받는다.
+ * 여기까지는 뜻대로 돈다.
+ *
+ * 그런데 그 이벤트를 `preventDefault()` 하면 Vite 헬퍼가 이렇게 한다(vite 소스 그대로):
+ *
+ *     function handlePreloadError(err) {
+ *       const e = new Event('vite:preloadError', { cancelable: true })
+ *       window.dispatchEvent(e)
+ *       if (!e.defaultPrevented) throw err      // ← 막으면 안 던진다
+ *     }
+ *     return baseModule().catch(handlePreloadError)   // ← 안 던지니 undefined 로 resolve
+ *
+ * **`location.reload()` 는 곧바로 멈추지 않는다.** 새 판이 뜨기 전까지 React 는 계속
+ * 그리고, `React.lazy` 는 resolve 된 `undefined` 의 `.default` 를 읽는다 —
+ * `Cannot read properties of undefined (reading 'default')`. 운영에서 이 오류가
+ * 07-09 ~ 08-28 동안 **아홉 사람에게 열세 번** 났다(/today·/customers·/my-word-table·
+ * /word-pairs·/word-management·/training-store — 스택은 전부 vendor-react 의 lazy 초기화).
+ *
+ * 즉 복구는 되는데 그 길목에서 **오류 화면을 한 번 띄우고 가짜 보고를 남기고** 있었다.
+ *
+ * ── 어떻게 고치나 ──
+ * 새로고침을 걸어 둔 동안에는 `lazy` 가 아무것도 결정하지 않게 한다(`lazyPage` 가
+ * 영영 resolve 하지 않는 약속을 돌려 Suspense 를 그대로 둔다). 그러려면 "지금 새로고침이
+ * 예약돼 있나"를 물을 수 있어야 해서, 그 판단을 여기 한 곳에 둔다.
+ */
+/**
+ * 배포 skew 로 판단되면 1회만 새로고침해 새 index.html 을 받는다.
+ * 앱이 `vite:preloadError`(또는 청크 로드 실패)를 받았을 때 부른다.
+ * @returns 새로고침을 걸었으면 true. 이미 최근에 걸었으면 false(진짜 오류로 넘긴다).
+ * @public
+ */
+export declare function recoverFromSkew(now?: number): boolean;
+
 /** getBoundingClientRect()만 있으면 되는 최소 인터페이스(주로 이벤트의 currentTarget). */
 declare type Rectable = {
     getBoundingClientRect(): DOMRect;
@@ -5875,6 +5937,15 @@ export declare interface SideNavProps {
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
 }
 
+/**
+ * 새로고침을 걸어 두었고 아직 새 판이 안 떴는가.
+ * @public
+ *
+ * `location.reload()` 가 비동기라 그 사이에 React 가 계속 도는데, 그동안 화면에
+ * 무엇을 그릴지 정하는 데 쓴다 — **아무것도 안 그리는 것이 맞다.** 곧 판이 바뀐다.
+ */
+export declare function skewReloadPending(now?: number): boolean;
+
 /**
  * 가로/세로 슬라이더. 접근성·키보드 지원을 위해 input[type=range] 기반.
  * 채워진 부분은 --slider-pct CSS 변수로 그라데이션 처리한다.

package/dist/packages/core/src/utils/chunkSkew.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 배포 skew 복구 — 그리고 그 복구가 내던 오류 화면.
+ *
+ * ── 무엇이 문제였나 ──
+ * 새 배포로 청크 해시가 바뀌면 캐시된 옛 index.html 이 사라진 청크를 부른다. Vite 는
+ * `vite:preloadError` 를 던지고, 우리는 그때 한 번 새로고침해 새 index.html 을 받는다.
+ * 여기까지는 뜻대로 돈다.
+ *
+ * 그런데 그 이벤트를 `preventDefault()` 하면 Vite 헬퍼가 이렇게 한다(vite 소스 그대로):
+ *
+ *     function handlePreloadError(err) {
+ *       const e = new Event('vite:preloadError', { cancelable: true })
+ *       window.dispatchEvent(e)
+ *       if (!e.defaultPrevented) throw err      // ← 막으면 안 던진다
+ *     }
+ *     return baseModule().catch(handlePreloadError)   // ← 안 던지니 undefined 로 resolve
+ *
+ * **`location.reload()` 는 곧바로 멈추지 않는다.** 새 판이 뜨기 전까지 React 는 계속
+ * 그리고, `React.lazy` 는 resolve 된 `undefined` 의 `.default` 를 읽는다 —
+ * `Cannot read properties of undefined (reading 'default')`. 운영에서 이 오류가
+ * 07-09 ~ 08-28 동안 **아홉 사람에게 열세 번** 났다(/today·/customers·/my-word-table·
+ * /word-pairs·/word-management·/training-store — 스택은 전부 vendor-react 의 lazy 초기화).
+ *
+ * 즉 복구는 되는데 그 길목에서 **오류 화면을 한 번 띄우고 가짜 보고를 남기고** 있었다.
+ *
+ * ── 어떻게 고치나 ──
+ * 새로고침을 걸어 둔 동안에는 `lazy` 가 아무것도 결정하지 않게 한다(`lazyPage` 가
+ * 영영 resolve 하지 않는 약속을 돌려 Suspense 를 그대로 둔다). 그러려면 "지금 새로고침이
+ * 예약돼 있나"를 물을 수 있어야 해서, 그 판단을 여기 한 곳에 둔다.
+ */
+/**
+ * 배포 skew 로 판단되면 1회만 새로고침해 새 index.html 을 받는다.
+ * 앱이 `vite:preloadError`(또는 청크 로드 실패)를 받았을 때 부른다.
+ * @returns 새로고침을 걸었으면 true. 이미 최근에 걸었으면 false(진짜 오류로 넘긴다).
+ * @public
+ */
+export declare function recoverFromSkew(now?: number): boolean;
+/**
+ * 새로고침을 걸어 두었고 아직 새 판이 안 떴는가.
+ * @public
+ *
+ * `location.reload()` 가 비동기라 그 사이에 React 가 계속 도는데, 그동안 화면에
+ * 무엇을 그릴지 정하는 데 쓴다 — **아무것도 안 그리는 것이 맞다.** 곧 판이 바뀐다.
+ */
+export declare function skewReloadPending(now?: number): boolean;

package/dist/packages/core/src/utils/chunkSkew.js

@@ -0,0 +1,70 @@
+/**
+ * 배포 skew 복구 — 그리고 그 복구가 내던 오류 화면.
+ *
+ * ── 무엇이 문제였나 ──
+ * 새 배포로 청크 해시가 바뀌면 캐시된 옛 index.html 이 사라진 청크를 부른다. Vite 는
+ * `vite:preloadError` 를 던지고, 우리는 그때 한 번 새로고침해 새 index.html 을 받는다.
+ * 여기까지는 뜻대로 돈다.
+ *
+ * 그런데 그 이벤트를 `preventDefault()` 하면 Vite 헬퍼가 이렇게 한다(vite 소스 그대로):
+ *
+ *     function handlePreloadError(err) {
+ *       const e = new Event('vite:preloadError', { cancelable: true })
+ *       window.dispatchEvent(e)
+ *       if (!e.defaultPrevented) throw err      // ← 막으면 안 던진다
+ *     }
+ *     return baseModule().catch(handlePreloadError)   // ← 안 던지니 undefined 로 resolve
+ *
+ * **`location.reload()` 는 곧바로 멈추지 않는다.** 새 판이 뜨기 전까지 React 는 계속
+ * 그리고, `React.lazy` 는 resolve 된 `undefined` 의 `.default` 를 읽는다 —
+ * `Cannot read properties of undefined (reading 'default')`. 운영에서 이 오류가
+ * 07-09 ~ 08-28 동안 **아홉 사람에게 열세 번** 났다(/today·/customers·/my-word-table·
+ * /word-pairs·/word-management·/training-store — 스택은 전부 vendor-react 의 lazy 초기화).
+ *
+ * 즉 복구는 되는데 그 길목에서 **오류 화면을 한 번 띄우고 가짜 보고를 남기고** 있었다.
+ *
+ * ── 어떻게 고치나 ──
+ * 새로고침을 걸어 둔 동안에는 `lazy` 가 아무것도 결정하지 않게 한다(`lazyPage` 가
+ * 영영 resolve 하지 않는 약속을 돌려 Suspense 를 그대로 둔다). 그러려면 "지금 새로고침이
+ * 예약돼 있나"를 물을 수 있어야 해서, 그 판단을 여기 한 곳에 둔다.
+ */
+const SKEW_KEY = 'chunk-reload-ts';
+/** 이 시간 안에 다시 실패하면 배포 skew 가 아니라 진짜 오류로 본다(무한 새로고침 방지). */
+const COOLDOWN_MS = 10_000;
+function 마지막시각() {
+    try {
+        return Number(sessionStorage.getItem(SKEW_KEY) || 0);
+    }
+    catch {
+        /* 사생활 보호 모드 등에서 sessionStorage 가 막힌다. 못 읽으면 '없음' 으로 본다 —
+           그러면 새로고침을 한 번 더 하게 될 뿐, 화면이 멈추지는 않는다. */
+        return 0;
+    }
+}
+/**
+ * 배포 skew 로 판단되면 1회만 새로고침해 새 index.html 을 받는다.
+ * 앱이 `vite:preloadError`(또는 청크 로드 실패)를 받았을 때 부른다.
+ * @returns 새로고침을 걸었으면 true. 이미 최근에 걸었으면 false(진짜 오류로 넘긴다).
+ * @public
+ */
+export function recoverFromSkew(now = Date.now()) {
+    if (now - 마지막시각() <= COOLDOWN_MS)
+        return false;
+    try {
+        sessionStorage.setItem(SKEW_KEY, String(now));
+    }
+    catch { /* 못 써도 새로고침은 한다 */ }
+    window.location.reload();
+    return true;
+}
+/**
+ * 새로고침을 걸어 두었고 아직 새 판이 안 떴는가.
+ * @public
+ *
+ * `location.reload()` 가 비동기라 그 사이에 React 가 계속 도는데, 그동안 화면에
+ * 무엇을 그릴지 정하는 데 쓴다 — **아무것도 안 그리는 것이 맞다.** 곧 판이 바뀐다.
+ */
+export function skewReloadPending(now = Date.now()) {
+    const last = 마지막시각();
+    return last > 0 && now - last <= COOLDOWN_MS;
+}

package/dist/packages/core/src/utils/lazyPage.d.ts

@@ -0,0 +1,23 @@
+import { type ComponentType, type LazyExoticComponent } from 'react';
+/**
+ * 화면을 늦게 받아 오는 자리 — `lazy()` 를 그냥 쓰지 않고 이걸 쓴다.
+ *
+ * 맨 `lazy(() => import(…))` 는 **모듈이 undefined 로 와도 그대로 `.default` 를 읽는다.**
+ * 그 일이 실제로 난다: 배포 skew 복구가 `vite:preloadError` 를 `preventDefault()` 하면
+ * Vite 헬퍼의 `catch` 가 아무것도 안 던지고 undefined 로 resolve 한다(자세한 것은
+ * `chunkSkew.ts`). 그러면 새로고침이 이미 걸려 있는데도 그 틈에 React 가
+ * `undefined.default` 를 읽어 **오류 화면이 한 번 뜨고 가짜 보고가 남는다.**
+ *
+ * 두 가지를 한다.
+ *  1. **새로고침이 예약돼 있으면 아무것도 결정하지 않는다** — 영영 resolve 하지 않는
+ *     약속을 돌려 Suspense 를 그대로 둔다. 곧 새 판이 뜬다.
+ *  2. 그게 아닌데 모듈이 이상하면 **어느 화면인지 적어** 던진다. 지금까지 이 오류는
+ *     스택이 통째로 vendor-react 안이라(minify 된 `q`) 어느 화면에서 났는지 알 수 없었다.
+ *
+ * Vite 가 아닌 번들러(Next 등)에서는 `vite:preloadError` 가 오지 않으니 이 감싸개는
+ * "모듈이 이상하면 어느 화면인지 적어 던진다" 만 한다 — 그것만으로도 맨 `lazy` 보다 낫다.
+ * @public
+ */
+export declare function lazyPage<T extends ComponentType<any>>(name: string, load: () => Promise<{
+    default: T;
+} | undefined>): LazyExoticComponent<T>;

package/dist/packages/core/src/utils/lazyPage.js

@@ -0,0 +1,45 @@
+import { lazy } from 'react';
+import { skewReloadPending } from './chunkSkew';
+/**
+ * 화면을 늦게 받아 오는 자리 — `lazy()` 를 그냥 쓰지 않고 이걸 쓴다.
+ *
+ * 맨 `lazy(() => import(…))` 는 **모듈이 undefined 로 와도 그대로 `.default` 를 읽는다.**
+ * 그 일이 실제로 난다: 배포 skew 복구가 `vite:preloadError` 를 `preventDefault()` 하면
+ * Vite 헬퍼의 `catch` 가 아무것도 안 던지고 undefined 로 resolve 한다(자세한 것은
+ * `chunkSkew.ts`). 그러면 새로고침이 이미 걸려 있는데도 그 틈에 React 가
+ * `undefined.default` 를 읽어 **오류 화면이 한 번 뜨고 가짜 보고가 남는다.**
+ *
+ * 두 가지를 한다.
+ *  1. **새로고침이 예약돼 있으면 아무것도 결정하지 않는다** — 영영 resolve 하지 않는
+ *     약속을 돌려 Suspense 를 그대로 둔다. 곧 새 판이 뜬다.
+ *  2. 그게 아닌데 모듈이 이상하면 **어느 화면인지 적어** 던진다. 지금까지 이 오류는
+ *     스택이 통째로 vendor-react 안이라(minify 된 `q`) 어느 화면에서 났는지 알 수 없었다.
+ *
+ * Vite 가 아닌 번들러(Next 등)에서는 `vite:preloadError` 가 오지 않으니 이 감싸개는
+ * "모듈이 이상하면 어느 화면인지 적어 던진다" 만 한다 — 그것만으로도 맨 `lazy` 보다 낫다.
+ * @public
+ */
+/* 서명은 React 의 `lazy` 를 그대로 따른다 — 화면마다 props 가 달라서, 여기서 좁히면
+   쓰는 쪽이 전부 `Property 'userId' does not exist` 로 막힌다(실제로 그렇게 됐다).
+   React 자신도 같은 이유로 이 자리에 any 를 쓴다(@types/react 의 lazy 서명). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function lazyPage(name, 
+/* 반환 타입에 undefined 를 적어 둔다 — 실제로 그렇게 온다(아래 참고). 타입이
+   "그럴 리 없다"고 말하면 부르는 쪽이 `.then(m => ({ default: m.X }))` 처럼 모듈을
+   그대로 읽는 코드를 쓰게 되고, 그러면 여기 닿기도 전에 터진다. */
+load) {
+    return lazy(async () => {
+        /* **undefined 로 resolve 될 수 있다.** 타입은 그럴 리 없다고 하지만 실제로 그렇게 온다
+           (배포 skew 복구가 preventDefault 한 뒤). 타입을 믿지 말고 확인한다. */
+        const mod = await load();
+        if (mod && typeof mod === 'object' && 'default' in mod) {
+            return mod;
+        }
+        /* 여기 오는 길은 사실상 하나뿐이다 — 청크를 못 받아 복구가 도는 중. 새 판을
+           기다린다. 영영 resolve 하지 않는 약속을 돌려 React 가 이 경계를 건드리지 않게 한다. */
+        if (skewReloadPending())
+            return new Promise(() => { });
+        throw new Error(`[lazyPage] ${name}: 화면 모듈을 받지 못했습니다(default 내보내기 없음). ` +
+            '배포 직후라면 새로고침으로 풀립니다.');
+    });
+}

package/dist/packages/core/src/utils.d.ts

@@ -55,4 +55,6 @@ export { wordContainsChoseong, wordContainsJungseong, wordContainsJongseong, wor
 export { isSyllablePattern, matchesSyllablePattern, validateSyllableSearchInput, patternToComposition, matchesWordQuery, searchAndRankWords } from './utils/koreanSyllable';
 export { PLAN_FEATURES, PLAN_LIMITS, TIER_RANK, getPlanTier, isManagerTier, type PlanTier, type DataLevel, type PlanFeatures, type PlanLimits, } from './utils/planFeatures';
 export { WORD_SUGGESTION_WEEKLY_QUOTA, WORD_SUGGESTION_ACCOUNT_LIMIT, WORD_SUGGESTION_EXISTING_ERROR, isThisWeekPick, } from './utils/wordSuggestionPolicy';
+export { recoverFromSkew, skewReloadPending } from './utils/chunkSkew';
+export { lazyPage } from './utils/lazyPage';
 export { CORE_VERSION } from './version';

package/dist/packages/core/src/utils.js

@@ -44,4 +44,6 @@ export { PLAN_FEATURES, PLAN_LIMITS, TIER_RANK, getPlanTier, isManagerTier, } fr
    말귀어드민(단어 제안 관리)이 같은 숫자를 봐야 하는데, 한쪽 화면 폴더에 두면
    다른 쪽이 그 폴더 없이는 빌드되지 않는다. 값과 순수 함수뿐이다. */
 export { WORD_SUGGESTION_WEEKLY_QUOTA, WORD_SUGGESTION_ACCOUNT_LIMIT, WORD_SUGGESTION_EXISTING_ERROR, isThisWeekPick, } from './utils/wordSuggestionPolicy';
+export { recoverFromSkew, skewReloadPending } from './utils/chunkSkew';
+export { lazyPage } from './utils/lazyPage';
 export { CORE_VERSION } from './version';

package/dist/packages/core/src/version.d.ts

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.170.0";
+export declare const CORE_VERSION = "0.171.0";

package/dist/packages/core/src/version.js

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export const CORE_VERSION = '0.170.0';
+export const CORE_VERSION = '0.171.0';