npm - ima2-gen - Versions diffs - 2.0.15 → 2.0.16 - Mend

ima2-gen 2.0.15 → 2.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (125) hide show

package/README.md +30 -0
package/bin/commands/skill.js +336 -17
package/bin/ima2.js +22 -2
package/bin/lib/doctor-checks.js +6 -4
package/config.js +1 -0
package/docs/CLI.md +25 -3
package/docs/PROMPT_STUDIO.ko.md +29 -0
package/docs/PROMPT_STUDIO.md +31 -0
package/docs/migration/runtime-test-inventory.md +7 -1
package/lib/agentImageVideoGen.js +8 -0
package/lib/agentQueueStore.js +36 -10
package/lib/agentQueueWorker.js +79 -7
package/lib/agentRuntime.js +2 -0
package/lib/assetLifecycle.js +40 -8
package/lib/canvasVersionStore.js +86 -0
package/lib/cardNewsGenerator.js +37 -3
package/lib/cardNewsJobStore.js +10 -0
package/lib/cardNewsManifestStore.js +6 -12
package/lib/cardNewsPath.js +25 -0
package/lib/db.js +2 -0
package/lib/generatePipeline.js +474 -0
package/lib/generationInputValidation.js +32 -0
package/lib/grokImageCore.js +18 -1
package/lib/historyIndex.js +11 -4
package/lib/historyList.js +3 -0
package/lib/imageMetadata.js +3 -0
package/lib/inflight.js +30 -3
package/lib/multimodePipeline.js +462 -0
package/lib/nodeGeneration.js +440 -0
package/lib/nodeValidation.js +23 -0
package/lib/oauthProxy/generators.js +3 -246
package/lib/oauthProxy/multimodeGenerators.js +251 -0
package/lib/routeHelpers.js +9 -2
package/package.json +2 -2
package/routes/agent.js +4 -4
package/routes/canvasVersions.js +21 -1
package/routes/cardNews.js +2 -1
package/routes/edit.js +25 -9
package/routes/events.js +5 -1
package/routes/generate.js +2 -481
package/routes/keys.js +31 -39
package/routes/multimode.js +2 -502
package/routes/nodes.js +3 -448
package/routes/video.js +12 -3
package/routes/videoExtended.js +19 -4
package/server.js +53 -1
package/skills/ima2/SKILL.md +204 -0
package/skills/ima2-front/SKILL.md +611 -0
package/skills/ima2-front/references/a11y-patterns.md +134 -0
package/skills/ima2-front/references/aesthetics.md +327 -0
package/skills/ima2-front/references/anti-slop.md +241 -0
package/skills/ima2-front/references/asset-requirements.md +431 -0
package/skills/ima2-front/references/brand-asset-sourcing.md +122 -0
package/skills/ima2-front/references/color-system.md +132 -0
package/skills/ima2-front/references/consistency-locks.md +20 -0
package/skills/ima2-front/references/crud-ui.md +53 -0
package/skills/ima2-front/references/dropdown-layer.md +110 -0
package/skills/ima2-front/references/i18n-global.md +104 -0
package/skills/ima2-front/references/iterative-design.md +90 -0
package/skills/ima2-front/references/korea-2026.md +174 -0
package/skills/ima2-front/references/layout-discipline.md +161 -0
package/skills/ima2-front/references/liquid-glass.md +181 -0
package/skills/ima2-front/references/logo-sections.md +194 -0
package/skills/ima2-front/references/mobile-ux.md +144 -0
package/skills/ima2-front/references/performance-budget.md +106 -0
package/skills/ima2-front/references/preflight-full.md +58 -0
package/skills/ima2-front/references/product-density.md +53 -0
package/skills/ima2-front/references/prototype-variants.md +54 -0
package/skills/ima2-front/references/reference-capture.md +120 -0
package/skills/ima2-front/references/responsive-viewport.md +139 -0
package/skills/ima2-front/references/seo-baseline.md +123 -0
package/skills/ima2-front/references/soft-3d-asset-gates.md +70 -0
package/skills/ima2-front/references/stacks/astro.md +204 -0
package/skills/ima2-front/references/stacks/mobile-native.md +281 -0
package/skills/ima2-front/references/stacks/nextjs.md +219 -0
package/skills/ima2-front/references/stacks/react.md +264 -0
package/skills/ima2-front/references/stacks/svelte.md +235 -0
package/skills/ima2-front/references/stacks/vanilla.md +226 -0
package/skills/ima2-front/references/theme-switching.md +82 -0
package/skills/ima2-front/references/top-bar.md +126 -0
package/skills/ima2-front/references/typography-wrapping.md +270 -0
package/skills/ima2-front/references/ux-writing-ko.md +62 -0
package/skills/ima2-front/references/visual-verification.md +102 -0
package/skills/ima2-uiux/SKILL.md +477 -0
package/skills/ima2-uiux/references/anti-slop-judgment.md +39 -0
package/skills/ima2-uiux/references/color-system.md +80 -0
package/skills/ima2-uiux/references/design-isms.md +194 -0
package/skills/ima2-uiux/references/design-read-example.md +33 -0
package/skills/ima2-uiux/references/design-system-bootstrap.md +133 -0
package/skills/ima2-uiux/references/favicon-logo.md +355 -0
package/skills/ima2-uiux/references/form-patterns.md +118 -0
package/skills/ima2-uiux/references/intent-discovery-ladder.md +86 -0
package/skills/ima2-uiux/references/korean-design-vocabulary.md +52 -0
package/skills/ima2-uiux/references/layout-macrostructures.md +54 -0
package/skills/ima2-uiux/references/logo-trust-sections.md +96 -0
package/skills/ima2-uiux/references/mobile-native-ux.md +207 -0
package/skills/ima2-uiux/references/product-personalities.md +118 -0
package/skills/ima2-uiux/references/responsive-nav.md +66 -0
package/skills/ima2-uiux/references/typography-line-breaks.md +193 -0
package/skills/ima2-uiux/references/ux-preflight.md +65 -0
package/skills/ima2-uiux/references/ux-states.md +197 -0
package/skills/ima2-uiux/references/visual-hierarchy.md +115 -0
package/ui/dist/.vite/manifest.json +13 -13
package/ui/dist/assets/AgentWorkspace-CtYt4SF5.js +3 -0
package/ui/dist/assets/{CardNewsWorkspace-Cdxn1ohU.js → CardNewsWorkspace-DN5cVqG5.js} +1 -1
package/ui/dist/assets/GenerationRequestLogPanel-DnmUQdKR.js +1 -0
package/ui/dist/assets/{NodeCanvas-C67sLboA.js → NodeCanvas-CxpfIBI0.js} +1 -1
package/ui/dist/assets/PromptBuilderPanel-C2R3ObtR.js +2 -0
package/ui/dist/assets/{PromptImportDialog-DeQXsEEv.js → PromptImportDialog-BIxz_yEx.js} +2 -2
package/ui/dist/assets/PromptImportDiscoverySection-BQTlPMME.js +1 -0
package/ui/dist/assets/PromptImportFolderSection-Ds_Th9O3.js +1 -0
package/ui/dist/assets/{PromptLibraryPanel-Db3xEPM_.js → PromptLibraryPanel-Rs4l45pV.js} +2 -2
package/ui/dist/assets/{SettingsWorkspace-BDk_1W-V.js → SettingsWorkspace-p1AZ6uT9.js} +1 -1
package/ui/dist/assets/index-0-_vgFGs.js +4 -0
package/ui/dist/assets/index-Dm3pFxV4.js +23 -0
package/ui/dist/assets/index-J8yDF3Ch.css +1 -0
package/ui/dist/index.html +2 -2
package/ui/dist/assets/AgentWorkspace-DAg_7zpY.js +0 -3
package/ui/dist/assets/GenerationRequestLogPanel-C_qvEUi2.js +0 -1
package/ui/dist/assets/PromptBuilderPanel-DjvVdAie.js +0 -2
package/ui/dist/assets/PromptImportDiscoverySection-CrwyUKYI.js +0 -1
package/ui/dist/assets/PromptImportFolderSection-CToGMqYE.js +0 -1
package/ui/dist/assets/index-2oG6in1i.css +0 -1
package/ui/dist/assets/index-CoxMOXAU.js +0 -23
package/ui/dist/assets/index-p8egnGHk.js +0 -4

package/skills/ima2-front/references/stacks/vanilla.md ADDED Viewed

@@ -0,0 +1,226 @@
+# Vanilla Stack — HTML + CSS + JS (No Framework)
+Rules for building production-quality frontends without React/Vue/etc.
+Read `core/aesthetics.md` + `core/anti-slop.md` first.
+---
+## Core Principle: Zero Dependencies
+Single self-contained HTML files with inline CSS/JS. No npm, no build tools, no bundler.
+The file IS the deliverable.
+---
+## Structure
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Page Title</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;500;700&display=swap" rel="stylesheet" />
+  <style>
+    /* === DESIGN TOKENS === */
+    :root {
+      --color-primary: #0ea5e9;
+      --color-surface: #fafafa;
+      --color-text: #18181b;
+      --color-muted: #71717a;
+      --font-display: 'Outfit', sans-serif;
+      --font-body: 'Outfit', sans-serif;
+      --radius: 0.75rem;
+      --max-width: 1200px;
+    }
+    /* === RESET === */
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: var(--font-body); color: var(--color-text); background: var(--color-surface); }
+    /* === LAYOUT === */
+    /* ... */
+    /* === COMPONENTS === */
+    /* ... */
+    /* === ANIMATIONS === */
+    /* ... */
+    /* === RESPONSIVE === */
+    @media (max-width: 768px) { /* ... */ }
+    /* === REDUCED MOTION === */
+    @media (prefers-reduced-motion: reduce) {
+      *, *::before, *::after {
+        animation-duration: 0.01ms !important;
+        transition-duration: 0.01ms !important;
+      }
+    }
+  </style>
+</head>
+<body>
+  <!-- Semantic HTML -->
+  <script>
+    // Minimal JS — progressive enhancement only
+  </script>
+</body>
+</html>
+```
+---
+## Typography
+Use fonts from **Google Fonts** or **Fontshare** — never system fonts.
+```html
+<!-- Fontshare (free, high quality) -->
+<link href="https://api.fontshare.com/v2/css?f[]=satoshi@400;500;700&display=swap" rel="stylesheet" />
+<!-- Google Fonts -->
+<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;500;700&display=swap" rel="stylesheet" />
+```
+### Fluid Typography (Mandatory)
+```css
+h1 { font-size: clamp(2rem, 1rem + 3.6vw, 4rem); }
+h2 { font-size: clamp(1.5rem, 1rem + 1.4vw, 2.25rem); }
+p  { font-size: clamp(1rem, 0.95rem + 0.2vw, 1.125rem); }
+```
+**NEVER** use fixed `px` for text. Always `clamp()`.
+---
+## CSS Animation (Preferred over JS)
+### Staggered Reveal on Load
+```css
+.reveal {
+  opacity: 0;
+  transform: translateY(20px);
+  animation: fadeUp 0.6s ease forwards;
+}
+.reveal:nth-child(1) { animation-delay: 0.1s; }
+.reveal:nth-child(2) { animation-delay: 0.2s; }
+.reveal:nth-child(3) { animation-delay: 0.3s; }
+@keyframes fadeUp {
+  to { opacity: 1; transform: translateY(0); }
+}
+```
+### CSS Custom Property for Stagger Index
+```css
+.reveal {
+  animation-delay: calc(var(--index, 0) * 100ms);
+}
+```
+```html
+<div class="reveal" style="--index: 0">First</div>
+<div class="reveal" style="--index: 1">Second</div>
+```
+### Hover Effects
+```css
+.card {
+  transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1),
+              box-shadow 0.3s ease;
+}
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 20px 40px -15px rgba(0,0,0,0.08);
+}
+```
+---
+## Viewport Fitting (Critical for Full-Page Layouts)
+```css
+.section-full {
+  min-height: 100dvh; /* NOT 100vh — iOS Safari breaks */
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+}
+```
+**Content Density Limits per Section:**
+| Type         | Maximum                                 |
+| ------------ | --------------------------------------- |
+| Hero         | 1 heading + 1 subtitle + 1 CTA          |
+| Content      | 1 heading + 4-6 bullets OR 2 paragraphs |
+| Feature grid | 1 heading + 6 cards max (2×3)           |
+| Quote        | 1 quote (max 3 lines) + attribution     |
+Content exceeds limits? Split into multiple sections.
+---
+## Responsive Layout
+```css
+/* Mobile-first */
+.grid {
+  display: grid;
+  gap: 1.5rem;
+  grid-template-columns: 1fr;
+}
+@media (min-width: 768px) {
+  .grid { grid-template-columns: repeat(2, 1fr); }
+}
+@media (min-width: 1024px) {
+  .grid { grid-template-columns: repeat(3, 1fr); }
+}
+/* Container */
+.container {
+  width: 100%;
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 0 1rem;
+}
+```
+**NEVER** use `calc()` flexbox math. Always CSS Grid.
+---
+## Progressive Enhancement
+1. Content readable without JS
+2. Layout works without CSS animations
+3. JS adds interactivity, not structure
+4. Use `<noscript>` for critical JS-dependent features
+---
+## Semantic HTML (Mandatory)
+```html
+<header>...</header>
+<nav aria-label="Main navigation">...</nav>
+<main id="main-content">
+  <section aria-labelledby="features-heading">
+    <h2 id="features-heading">Features</h2>
+  </section>
+</main>
+<footer>...</footer>
+```
+Use `<button>` for actions, `<a>` for navigation. Never `<div onclick>`.
+---
+## File Delivery
+Output a single `.html` file. All CSS in `<style>`, all JS in `<script>`.
+Every section needs `/* === SECTION NAME === */` comments.
+The file should be openable directly in a browser — no build step.

package/skills/ima2-front/references/theme-switching.md ADDED Viewed

@@ -0,0 +1,82 @@
+# Theme / Dark Mode
+## Implementation
+Use `data-theme` attribute on `<html>`, not class-based toggle.
+```css
+:root {
+  --bg-primary: oklch(98% 0 0);
+  --text-primary: oklch(15% 0 0);
+}
+:root[data-theme="dark"] {
+  --bg-primary: oklch(12% 0 0);
+  --text-primary: oklch(92% 0 0);
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --bg-primary: oklch(12% 0 0);
+    --text-primary: oklch(92% 0 0);
+  }
+}
+```
+- `data-theme` takes precedence over media query
+- System preference is the fallback when no explicit choice
+- All colors MUST use CSS custom properties
+  (token layering + `oklch()`/`light-dark()` mechanics: `color-system.md`)
+## Flash of Wrong Theme (FOWT) Prevention
+```html
+<script>
+  (function() {
+    var t = localStorage.getItem('theme');
+    if (t === 'dark' || t === 'light') {
+      document.documentElement.setAttribute('data-theme', t);
+    }
+  })();
+</script>
+```
+- Inline in `<head>`, before any stylesheet (< 200 bytes)
+- SSR: read theme cookie server-side, set `data-theme` in HTML response
+## Toggle Component
+Three states: Light → Dark → System → Light.
+- Store: `localStorage.setItem('theme', 'dark' | 'light' | 'system')`
+- `system` removes `data-theme`, lets media query decide
+- Accessible: `role="button"`, `aria-label="Switch to dark theme"`
+- Position: header or settings, never hidden in submenu
+## Theme Transition
+```css
+:root[data-theme-transitioning] * {
+  transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease !important;
+}
+```
+- Add transitioning attribute on toggle, remove after 200ms
+- Only transition color properties
+- Respect `prefers-reduced-motion`: skip transition
+- Never animate on page load
+## Component Checklist
+- [ ] All colors use custom properties
+- [ ] Shadows lighter in dark mode
+- [ ] White-background images get border in dark mode
+- [ ] SVG icons use `currentColor`
+- [ ] Borders use surface-level difference in dark mode
+- [ ] Charts/data-viz legible in both themes
+- [ ] Form inputs have sufficient contrast in both themes
+## Cross-references
+- Dark token derivation: `dev-uiux-design/references/color-system.md`
+- One theme per page: `consistency-locks.md`

package/skills/ima2-front/references/top-bar.md ADDED Viewed

@@ -0,0 +1,126 @@
+# Top Bar Composition - Implementation Guide
+Canonical owner for top-bar composition: geometry, slots, scroll-state
+contract, spawned surfaces, and verification hooks. Material recipes live in
+`liquid-glass.md`; do not duplicate opacity/blur recipes here. The top-bar
+domain GATE lives in this file (FE-TOPBAR-DOMAIN-01 below); broader brand/
+style judgment beyond that gate lives in `ima2-uiux`.
+---
+## Domain Gate (FE-TOPBAR-DOMAIN-01, STRICT)
+Liquid pill top bars are for expressive surfaces: landing, campaign,
+editorial, portfolio, brand, and visual product pages.
+Dashboards, admin, finance, government, B2B repeated-work tools, auth,
+payment, security, and developer consoles keep standard solid headers by
+default. Their chrome should be predictable, dense, and readable before it is
+expressive.
+## Geometry
+Prefer a floating detached pill bar only when the first viewport can support it.
+The bar must have a capped max-width, top inset, safe-area handling, and a
+single outer capsule radius (`9999px` or >= 24px).
+| Surface | Geometry | Notes |
+| --- | --- | --- |
+| Landing / campaign / portfolio | Floating detached pill | Legal when the hero has a calm bar zone and enough top breathing room. |
+| Editorial / brand story | Floating pill or quiet full-width | Choose based on reading comfort and hero image complexity. |
+| Consumer app shell | Full-width or compact solid header | Use pill only for promotional/home surfaces, not repeated workflows. |
+| Dashboard / admin / finance / gov / B2B tool | Full-width solid header | Avoid detached liquid chrome; preserve scanning and task speed. |
+STYLE_SAMPLE:
+```css
+.top-bar {
+  position: sticky;
+  top: max(12px, env(safe-area-inset-top));
+  z-index: 40;
+  width: min(calc(100% - 32px), 1120px);
+  margin-inline: auto;
+  border-radius: 9999px;
+}
+```
+## Slots
+Keep the bar sparse enough that the pill still reads as one piece of chrome:
+- Logo: use the real brand SVG; see `brand-asset-sourcing.md`.
+- Navigation: 2-5 links. More destinations move into a menu or full navigation
+  surface.
+- Controls: only include controls that earn their place in the first viewport
+  (for example theme, language, account, or search when essential).
+- CTA: one filled pill CTA is allowed. It must not create a row of competing
+  primary actions.
+Mobile collapses to logo + menu trigger. The menu opens a sheet or drawer with
+a complete tap path; do not rely on hover behavior on touch devices.
+## Scroll State (FE-TOPBAR-STATE-01, DEFAULT)
+Top bars may be scroll-adaptive:
+- At top: a lighter material state around 70-80% opacity is allowed only over a
+  hero authored with a calm bar zone behind the chrome.
+- Scrolled: use the near-opaque 85-95% opacity range and keep blur when the
+  selected material state calls for it.
+- Transition: animate `background-color` and `opacity` only. Do not morph size,
+  width, radius, or layout on blurred bars.
+- Accessibility supremacy: `FE-LIQUID-A11Y-01` in `liquid-glass.md` overrides
+  every state here. Reduced-transparency, increased-contrast, unsupported
+  `backdrop-filter`, or failed worst-case contrast collapses all states to
+  solid or near-opaque.
+STYLE_SAMPLE:
+```css
+.top-bar {
+  transition: background-color 180ms ease, opacity 180ms ease;
+}
+```
+## Hover Surfaces (FE-TOPBAR-HOVER-01, DEFAULT)
+Any surface spawned from the bar is unconditionally near-opaque, blur-free, and
+solid: dropdown, mega-menu, popover, account menu, language picker, or search
+panel. Content must remain legible over the busiest background that can appear
+behind it.
+Hover surfaces also need a tap path. Mobile uses the same visual skin where
+appropriate, but the interaction becomes a sheet, drawer, or proven picker
+primitive with correct ARIA and keyboard behavior.
+## Child Visuals
+Nested pill visuals are governed by `FE-PILL-NEST-01` in `liquid-glass.md`.
+Inside pill chrome, child controls render no capsule borders or outlines at
+rest. Solid fills are not restricted by that rule; use hierarchy and accent
+budget to decide how many strong fills the bar can carry.
+Use fill or tint, not rest-state capsule borders, for `aria-current` and active
+navigation state.
+## Accessibility
+The full bar and every spawned surface must be keyboard reachable:
+- Tab order enters the logo, links, controls, CTA, and spawned surfaces in a
+  predictable path.
+- Escape closes spawned surfaces and returns focus to the trigger.
+- Arrow-key behavior follows the underlying primitive pattern for menu,
+  combobox, listbox, or picker.
+- Sticky chrome never hides focused content; apply `scroll-margin-top` or
+  equivalent offsets to in-page targets.
+- Skip links remain visible and usable with the sticky bar present.
+## Verification Hooks
+Screenshot or otherwise inspect:
+- At-top and scrolled states over their real hero/background.
+- A bar-spawned hover surface over the busiest possible background.
+- Reduced-transparency / increased-contrast collapse to solid or near-opaque.
+- Mobile logo + menu trigger and the resulting sheet or drawer tap path.

package/skills/ima2-front/references/typography-wrapping.md ADDED Viewed

@@ -0,0 +1,270 @@
+# Typography Wrapping — CSS Text Control
+Production CSS for text wrapping, line breaks, orphan prevention, and readable line lengths.
+Apply globally in resets or design system base styles.
+---
+## Global Production Template (2026 Standard)
+```css
+/* Headings — balance for visual hierarchy */
+h1, h2, h3, h4, h5, h6,
+blockquote, figcaption, .hero-title {
+  text-wrap: balance;
+}
+/* Short descriptors (1-3 lines) — balance, NOT pretty */
+.hero-desc, .card-desc, .feature-desc,
+.caption, .subtitle, .blurb {
+  text-wrap: balance;
+}
+/* Body text (4+ lines) — pretty for orphan prevention */
+p, li, dt, dd, .prose {
+  text-wrap: pretty;
+}
+/* Editable content — stable for no-reflow typing */
+[contenteditable], .live-text {
+  text-wrap: stable;
+}
+/* Readable line lengths */
+h1 { max-width: 50ch; }
+h2 { max-width: 55ch; }
+h3 { max-width: 60ch; }
+p, li, article, .prose { max-width: 65ch; }
+/* Korean: wrap by 어절 (word), never mid-word. Scope to ko ONLY —
+   global keep-all degrades Chinese/Japanese wrapping (verified 2026-07-07,
+   MDN + Naver SmartStudio). */
+[lang|="ko"] {
+  word-break: keep-all;
+  overflow-wrap: break-word; /* escape hatch for long 어절 in narrow boxes */
+}
+/* URLs and unbreakable strings */
+a[href], code {
+  overflow-wrap: break-word;
+}
+/* Never-wrap elements */
+.cta-label, .badge, .nav-link, .tag {
+  white-space: nowrap;
+}
+```
+**Fallback for older browsers:**
+```css
+@supports not (text-wrap: balance) {
+  h1, h2, h3 { max-width: min(90vw, 45ch); }
+}
+```
+---
+## `text-wrap: balance`
+Distributes characters evenly across lines. Prevents long first line + stubby orphan last line.
+**When to use:** Headings, captions, blockquotes, hero titles, card titles.
+**When NOT to use:** Body paragraphs (performance cost, limited to ~6 lines in Chromium, 10 in Firefox).
+**Tailwind:** `text-balance`
+Test with both centered AND left-aligned headings. Combine with `max-width` in `ch` units for best results.
+---
+## `text-wrap: pretty`
+Higher-quality algorithm focused on the last few lines. Prevents typographic orphans.
+**When to use:** Body copy, articles, prose, content-heavy sections.
+**Tailwind:** `text-pretty`
+---
+## `text-wrap: stable`
+Prevents reflow of previous lines during editing. Content before the cursor stays fixed.
+**When to use:** `contenteditable`, note-taking fields, real-time collaborative editing, live chat input.
+---
+## Short Descriptors — `balance`, not `pretty`
+Text that is 1-3 lines long (hero subtitle, card description, caption, feature blurb) is NOT a body paragraph. `text-wrap: pretty` has no meaningful effect on 1-3 lines — it targets the tail of long paragraphs.
+**Use `text-wrap: balance` for all short descriptors.**
+```css
+/* Short descriptors — balance for orphan-free wrapping */
+.hero-desc, .card-desc, .feature-desc,
+.caption, .subtitle, .blurb {
+  text-wrap: balance;
+}
+```
+Add these to the Global Production Template alongside headings.
+### `-webkit-line-clamp` disables `text-wrap`
+When `-webkit-line-clamp` is active, the browser uses a legacy layout mode. `text-wrap: balance` and `pretty` have **zero effect**. If you need truncation with ellipsis, rely on `max-width` to control where breaks land — `text-wrap` cannot help.
+---
+## `max-width` in `ch` Units
+| Element | Recommended `max-width` | Rationale |
+|---------|------------------------|-----------|
+| Hero title | 40–45ch | Short, punchy, fits viewport |
+| **Hero subtitle/desc** | **35–40ch** | **Short descriptor — prevent orphans in 1-2 lines** |
+| Section title | 50–55ch | Room for longer phrases |
+| Card title | 30–35ch | Compact containers |
+| **Card description** | **30–35ch** | **Short descriptor — tight containers amplify orphans** |
+| **Caption / label** | **25–30ch** | **Short descriptor** |
+| Body paragraph | 60–65ch | Optimal readability (45–75ch range) |
+| Article/prose | 65ch | Standard reading measure |
+Combine with fluid typography:
+```css
+h1 {
+  font-size: clamp(2rem, 5vw + 1rem, 4rem);
+  max-width: min(90vw, 45ch);
+  text-wrap: balance;
+}
+```
+---
+## Rag Control
+| Problem | Solution |
+|---------|----------|
+| Uneven rag (jagged right edge) | `text-wrap: pretty` on paragraphs |
+| Orphaned last word | `text-wrap: pretty` or `text-wrap: balance` for short blocks |
+| Very long lines | `max-width: 65ch` |
+| Rivers in justified text | Avoid `text-align: justify` or add `hyphens: auto` + `lang` attribute |
+| Heading stubs | `text-wrap: balance` + `max-width` in `ch` |
+---
+## Korean Short Text — `pretty` Does Not Work
+`text-wrap: pretty` does NOT prevent orphans in Korean text under 3 lines. The algorithm targets the tail of long paragraphs; on short Korean text with `word-break: keep-all`, orphans like "합니다.", "화.", "입니다." pass through unchanged.
+**Mandatory rule for Korean short text (< 40 characters):** Always use `text-wrap: balance`. If `balance` still produces an orphan, adjust `max-width` by ±2-3ch.
+```css
+/* Korean short descriptors — explicit balance override */
+[lang="ko"] .hero-desc,
+[lang="ko"] .card-desc,
+[lang="ko"] .subtitle {
+  text-wrap: balance;
+  word-break: keep-all;
+}
+```
+This is the single most common Korean typography failure in AI-generated pages.
+---
+## `word-break` vs `overflow-wrap`
+| Scenario | Use |
+|----------|-----|
+| Long URLs in narrow containers | `overflow-wrap: break-word` |
+| Maximum flexibility with accurate sizing | `overflow-wrap: anywhere` |
+| Aggressive character-level breaking | `word-break: break-all` |
+| Korean 어절 (word) wrapping — `:lang(ko)` scope ONLY, degrades zh/ja globally | `word-break: keep-all` |
+| User-generated content | `overflow-wrap: anywhere` |
+**`word-break: break-word` is DEPRECATED** — use `overflow-wrap: break-word` instead.
+---
+## Responsive Heading Breaks
+Do NOT use manual `<br>` tags for line breaks. They break on different viewports.
+```css
+/* If you must use <br> for a specific breakpoint: */
+h1 br { display: none; }
+@media (min-width: 768px) { h1 br { display: block; } }
+```
+**Preferred approach:** Let `text-wrap: balance` + `max-width` handle it naturally.
+---
+## `widows` and `orphans` (Print Only)
+These CSS properties only work in multi-column layouts and paged media. NOT for standard web layouts.
+For web, use `text-wrap: pretty` instead.
+---
+## Production Pattern
+Common across Vercel, Linear, Stripe: `text-wrap: balance` on headings, `text-wrap: pretty` on body, `font-size: clamp()` for fluid scaling, tighter line-height (1.1–1.2) for headings.
+For Korean-specific typography considerations, see also `korea-2026.md`.
+---
+## Natural Phrase Breaks at Any Width (FE-WRAP-NATURAL-01, DEFAULT)
+Text MUST break at natural phrase boundaries — between thought units, never
+mid-word/mid-phrase — and it must hold at ANY container width, not only
+canonical breakpoints. Containers resize continuously (drag-resize,
+split-screen, foldables, mobile URL-bar dvh changes, container-query
+crossings); a heading that breaks well at 390/768/1024/1440 can still orphan
+at 700px. Control break OPPORTUNITIES (`keep-all`, `max-width` in `ch`,
+`text-wrap: balance`) instead of width-specific hacks (`<br>`, media-query
+text swaps).
+Korean facts (verified 2026-07-07, Tier-2: MDN, CSSWG Text 4, KLREQ, Chrome
+DevRel, Naver SmartStudio):
+- With `keep-all`, break opportunities are 어절 (space) boundaries;
+  `text-wrap` only CHOOSES among existing opportunities — it cannot create
+  Korean phrase boundaries.
+- `word-break: auto-phrase` ships for JAPANESE only (Chrome 119+); do NOT
+  rely on it for Korean. Treat it as ja-scoped progressive enhancement.
+- KLREQ line rules are real for Korean (not just Japanese kinsoku): closing
+  punctuation must not start a line; opening brackets must not end one;
+  number/symbol runs should not split.
+- Advanced editorial tactic: `Intl.Segmenter("ko", {granularity: "word"})`
+  (Baseline 2024) + render-time `<wbr>` insertion at approved phrase
+  boundaries under `keep-all`. Insert at RENDER time only — ZWSP/joiners
+  stored in canonical content break search/copy/diff.
+- Overflow risk: `keep-all` + long 어절 + narrow chips/buttons/table cells =
+  clipping; always pair with `overflow-wrap: break-word` (or `anywhere` for
+  user-generated/URL content — note it also shrinks min-content size).
+### Dynamic-Viewport Verification (checklist)
+- Sweep CONTAINER widths, not device presets: 160-900px in 8-16px steps for
+  headings, cards, buttons, chips, sidebars, resizable panes, table cells.
+- Test dvh/svh URL-bar changes, split-screen halves (640-1024px band, see
+  `responsive-viewport.md`), foldable-narrow panes, container-query
+  crossings, and 200% zoom / OS text scaling separately.
+- Assert no overflow: `scrollWidth <= clientWidth` on text containers, plus
+  screenshots for clipping/overlap at 2-3 arbitrary mid-widths.
+- Korean fixtures: long single 어절, no-space strings, mixed
+  Korean/Latin/number copy, URLs, punctuation-heavy lines; flag any
+  mid-syllable split where `keep-all` is expected.
+- Fluid type uses `clamp()` with rem/em bounds — never bare `vw`/`cqi` font
+  sizes (zoom/user-font-size must keep working).
+Judgment layer (when a break is "natural", review criteria):
+`dev-uiux-design/references/typography-line-breaks.md § Dynamic Rewrap Judgment`.
+## Sources
+- [MDN: text-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-wrap)
+- [Chrome: CSS text-wrap balance](https://developer.chrome.com/docs/css-ui/css-text-wrap-balance)