@santi020k/lumen 3.0.1 → 4.0.0

package/templates/shared/visual-blocks/src/lumen/product-blocks.ts

@@ -0,0 +1,224 @@
+/** Local recipe interactions. Applications own checkout, persistence, navigation, and authorization. */
+const announce = (root: HTMLElement, text: string): void => {
+  const status = root.querySelector<HTMLElement>('[data-block-status]')
+
+  if (status) status.textContent = text
+}
+
+const dispatch = (root: HTMLElement, name: string, detail: Readonly<Record<string, string>>): boolean => (
+  root.dispatchEvent(new CustomEvent(name, { bubbles: true, cancelable: true, detail }))
+)
+
+const updateBilling = (root: HTMLElement, billing: string): void => {
+  for (const button of root.querySelectorAll<HTMLElement>('[data-billing]')) button.setAttribute('aria-pressed', String(button.dataset.billing === billing))
+
+  for (const amount of root.querySelectorAll<HTMLElement>('[data-monthly][data-annual]')) {
+    const price = (billing === 'annual' ? amount.dataset.annual : amount.dataset.monthly) ?? '0'
+
+    amount.textContent = `$${price} / ${billing === 'annual' ? 'year' : 'month'}`
+  }
+}
+
+const bindPricingBlock = (root: HTMLElement): (() => void) => {
+  let billing = 'monthly'
+
+  const click = (event: MouseEvent): void => {
+    if (!(event.target instanceof Element)) return
+
+    const control = event.target.closest<HTMLElement>('[data-billing], [data-plan]')
+
+    if (control?.closest('[data-product-block]') !== root) return
+
+    if (control.dataset.billing) {
+      billing = control.dataset.billing
+
+      updateBilling(root, billing)
+    } else if (control.dataset.plan) {
+      dispatch(root, 'ui:plan-select', { billing, plan: control.dataset.plan })
+
+      announce(root, `Selected ${control.dataset.plan}, ${billing}.`)
+    }
+  }
+
+  root.addEventListener('click', click)
+
+  return () => {
+    root.removeEventListener('click', click)
+  }
+}
+
+const bindFeatureBlock = (root: HTMLElement): (() => void) => {
+  const click = (event: MouseEvent): void => {
+    if (!(event.target instanceof Element)) return
+
+    const button = event.target.closest<HTMLElement>('[data-feature]')
+
+    if (button?.closest('[data-product-block]') !== root) return
+
+    const feature = button.dataset.feature ?? 'plan'
+
+    for (const control of root.querySelectorAll<HTMLElement>('[data-feature]')) control.setAttribute('aria-pressed', String(control.dataset.feature === feature))
+
+    for (const panel of root.querySelectorAll<HTMLElement>('[data-feature-panel]')) panel.hidden = panel.dataset.featurePanel !== feature
+
+    announce(root, `Previewing ${feature}.`)
+  }
+
+  root.addEventListener('click', click)
+
+  return () => {
+    root.removeEventListener('click', click)
+  }
+}
+
+export const bindOnboardingBlock = (root: HTMLElement): (() => void) => {
+  const form = root.querySelector('form')
+  const input = root.querySelector<HTMLInputElement>('input[data-workspace-name], [data-workspace-name] input')
+
+  if (!form || !input) return () => undefined
+
+  let step = 0
+
+  const updateValidity = (): void => {
+    const next = root.querySelector<HTMLElement>('[data-onboarding-next]')
+    const disabled = !input.value.trim()
+
+    next?.toggleAttribute('disabled', disabled)
+
+    next?.classList.toggle('ui-button--disabled', disabled)
+  }
+
+  input.addEventListener('input', updateValidity)
+
+  updateValidity()
+
+  const sync = (): void => {
+    for (const panel of root.querySelectorAll<HTMLElement>('[data-onboarding-step]')) panel.hidden = Number(panel.dataset.onboardingStep) !== step
+
+    const review = root.querySelector<HTMLElement>('[data-workspace-review]')
+
+    if (review) review.textContent = input.value
+
+    const back = root.querySelector<HTMLElement>('[data-onboarding-back]')
+
+    if (back) back.hidden = step !== 1
+
+    const next = root.querySelector<HTMLButtonElement>('[data-onboarding-next]')
+
+    if (next) {
+      next.hidden = step === 2
+
+      next.textContent = step === 0 ? 'Continue' : 'Complete setup'
+    }
+
+    announce(root, `Step ${step + 1} of 3${step === 2 ? ': draft completed.' : '.'}`)
+
+    root.querySelector<HTMLElement>(`[data-onboarding-step="${step}"] h3`)?.focus()
+  }
+
+  const submit = (event: SubmitEvent): void => {
+    event.preventDefault()
+
+    if (!input.value.trim() || !form.reportValidity() || step === 2) return
+
+    if (step === 1 && !dispatch(root, 'ui:onboarding-complete', { workspace: input.value.trim() })) return
+
+    step++
+
+    sync()
+  }
+
+  const back = (event: MouseEvent): void => {
+    if (!(event.target instanceof Element)) return
+
+    if (event.target.closest('lumen-button[data-onboarding-next]')) {
+      form.requestSubmit()
+
+      return
+    }
+
+    if (!event.target.closest('[data-onboarding-back], [data-onboarding-edit]')) return
+
+    step = 0
+
+    sync()
+  }
+
+  form.addEventListener('submit', submit)
+
+  root.addEventListener('click', back)
+
+  return () => {
+    input.removeEventListener('input', updateValidity)
+
+    form.removeEventListener('submit', submit)
+
+    root.removeEventListener('click', back)
+  }
+}
+
+const bindCommandBlock = (root: HTMLElement): (() => void) => {
+  const click = (event: MouseEvent): void => {
+    if (!(event.target instanceof Element)) return
+
+    const command = event.target.closest<HTMLElement>('[data-workspace-command]')
+
+    if (command?.closest('[data-product-block]') !== root || !command.dataset.workspaceCommand) return
+
+    dispatch(root, 'ui:workspace-command', { command: command.dataset.workspaceCommand })
+
+    announce(root, `Selected: ${command.textContent}`)
+  }
+
+  root.addEventListener('click', click)
+
+  return () => {
+    root.removeEventListener('click', click)
+  }
+}
+
+const mountedBlocks = new WeakMap<HTMLElement, () => void>()
+
+export const mountProductBlocks = (scope: ParentNode): (() => void) => {
+  const cleanups: (() => void)[] = []
+
+  for (const root of scope.querySelectorAll<HTMLElement>('[data-product-block]')) {
+    if (mountedBlocks.has(root)) continue
+
+    let binding: (() => void) | undefined
+
+    switch (root.dataset.productBlock) {
+      case 'pricing': binding = bindPricingBlock(root)
+
+        break
+
+      case 'feature': binding = bindFeatureBlock(root)
+
+        break
+
+      case 'onboarding': binding = bindOnboardingBlock(root)
+
+        break
+
+      case 'command': binding = bindCommandBlock(root)
+
+        break
+    }
+
+    if (!binding) continue
+
+    mountedBlocks.set(root, binding)
+
+    const cleanup = binding
+
+    cleanups.push(() => {
+      cleanup()
+
+      mountedBlocks.delete(root)
+    })
+  }
+
+  return () => {
+    for (const cleanup of cleanups) cleanup()
+  }
+}

package/v4-migration.json

@@ -0,0 +1,447 @@
+{
+  "schemaVersion": 1,
+  "status": "approved",
+  "targetVersion": "4.0.0",
+  "policy": {
+    "compatibility": "Lumen 4 may deliberately replace v3 component and binary contracts. Consumer data, privacy, and release approval remain protected. Migration guidance documents externally visible changes.",
+    "versioning": "Prepare the coordinated v4 candidate locally. Publication requires separate approval of the final reviewed revision through the existing GitHub release workflow."
+  },
+  "changes": [
+    {
+      "id": "consumer-driven-component-polish",
+      "kind": "breaking",
+      "currentContract": "Consumers carry chart-label, hidden-state, clipboard, date-selection, and native-layout workarounds across older Lumen releases.",
+      "replacement": "Shared chart geometry and formatted axes, strict range selection, explicit clipboard recovery, accessible native layout controls, and a cross-framework image comparison primitive.",
+      "migration": "Use stable unique chart X identities; remove verified old chart/hidden patches; review button content selectors and loading activation; rebuild native consumers for changed initializer and formatter contracts.",
+      "evidence": [
+        "docs/lumen-4-consumer-audit.md",
+        "docs/lumen-4-readiness.md"
+      ],
+      "docs": [
+        "docs/migrating-to-lumen.md",
+        "docs/data-visualization.md",
+        "docs/ai-usage.md"
+      ],
+      "tests": [
+        "pnpm run validate",
+        "pnpm run test:a11y",
+        "swift test",
+        "cd packages/compose && ./gradlew test lint apiCheck"
+      ],
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements",
+        "@santi020k/lumen-react-native",
+        "LumenUI",
+        "com.santi020k:lumen-compose"
+      ],
+      "signals": [
+        "DatePicker",
+        "DateRange",
+        "Button",
+        "Chart",
+        "CopyButton",
+        "NavigationMenu",
+        "hidden="
+      ]
+    },
+    {
+      "id": "swift-native-control-polish",
+      "kind": "breaking",
+      "currentContract": "Eight v3 Swift initializer signatures do not expose compact chart, heatmap color scales, chart-data labels and formatting, slider-label, and symbol-selection options. The v3 icon enum lacks four reviewed catalog additions.",
+      "replacement": "Defaulted parameters provide bare chart frames, explicit plot height, heatmap color scales and legends, localized interval-chart data and formatting, optional slider headings, contextual symbol tint, and selection completion. The icon enum adds bangladeshiTaka, layoutGridCircles, letters, and printer3d.",
+      "migration": "Rebuild consumers against v4. Existing source calls generally retain defaults; method references and binary clients must adopt the new signatures. Exhaustive LumenIconName switches must handle the four new cases or provide an appropriate fallback. See native composition examples and the v4 migration guide.",
+      "packages": [
+        "LumenUI"
+      ],
+      "evidence": [
+        "docs/lumen-4-consumer-audit.md",
+        "docs/native-api-audit.md"
+      ],
+      "docs": [
+        "packages/swift/README.md",
+        "docs/native-patterns.md",
+        "docs/migrating-to-lumen.md"
+      ],
+      "tests": [
+        "swift test",
+        "pnpm run check:swift-api-baseline",
+        "pnpm run check:swift-source-compatibility"
+      ],
+      "swiftApiBreakages": [
+        "constructor LumenBarChart.init(label:series:layout:summary:labels:showData:selection:) has been removed",
+        "constructor LumenChartLabels.init(empty:notAvailable:size:viewData:formatHeatmapSummary:formatRangeSummary:formatSummary:) has been removed",
+        "constructor LumenHeatmap.init(label:data:summary:labels:showData:) has been removed",
+        "constructor LumenLineChart.init(label:series:heading:description:summary:labels:area:reference:showData:selection:) has been removed",
+        "constructor LumenSlider.init(_:value:in:step:valueLabel:) has been removed",
+        "constructor LumenSlider.init(_:value:in:step:valueLabel:onEditingChanged:) has been removed",
+        "constructor LumenSymbolPicker.init(_:selectedName:options:) has been removed",
+        "constructor LumenSymbolPickerButton.init(_:selectedName:options:) has been removed",
+        "enumelement LumenIconName.bangladeshiTaka has been added as a new enum case",
+        "enumelement LumenIconName.layoutGridCircles has been added as a new enum case",
+        "enumelement LumenIconName.letters has been added as a new enum case",
+        "enumelement LumenIconName.printer3d has been added as a new enum case"
+      ],
+      "signals": [
+        "LumenBarChart",
+        "LumenLineChart",
+        "LumenSlider",
+        "LumenSymbolPicker",
+        "LumenIconName",
+        "LumenHeatmap"
+      ]
+    },
+    {
+      "id": "native-sheet-accessibility-quality",
+      "kind": "breaking",
+      "currentContract": "SwiftUI and Compose sheets wrap unbounded content without configurable dismissal protection; native required-field and tab-panel descriptions include fixed English text.",
+      "replacement": "Native sheet scroll and dismissal policies, keyboard-safe content, compact-height and large-text fallbacks, explicit React Native focus targets, and caller-localized accessibility descriptions.",
+      "migration": "Rebuild SwiftUI and Compose consumers for the new sheet signatures. Set scrollable false for application-owned lazy or virtualized content. Supply translated requiredLabel and panelAccessibilityLabel in Compose and React Native when needed.",
+      "packages": [
+        "@santi020k/lumen-react-native",
+        "LumenUI",
+        "com.santi020k:lumen-compose"
+      ],
+      "evidence": [
+        "docs/lumen-4-native-quality.md"
+      ],
+      "docs": [
+        "docs/native-patterns.md",
+        "docs/migrating-to-lumen.md"
+      ],
+      "tests": [
+        "pnpm --filter @santi020k/lumen-react-native test",
+        "swift test",
+        "cd packages/compose && ./gradlew test lint apiCheck connectedDebugAndroidTest"
+      ],
+      "swiftApiBreakages": [
+        "func View.lumenSheet(isPresented:title:description:onDismiss:actions:content:) has been renamed to func lumenSheet(isPresented:title:description:dismissible:scrollable:onDismiss:actions:content:)",
+        "func View.lumenSheet(isPresented:title:description:onDismiss:actions:content:) has parameter 3 type change from () -> Swift.Void to Swift.Bool",
+        "func View.lumenSheet(isPresented:title:description:onDismiss:actions:content:) has parameter 4 type change from () -> Actions to Swift.Bool",
+        "func View.lumenSheet(isPresented:title:description:onDismiss:actions:content:) has parameter 5 type change from () -> SheetContent to () -> Swift.Void",
+        "func View.lumenSheet(isPresented:title:description:onDismiss:content:) has been renamed to func lumenSheet(isPresented:title:description:dismissible:scrollable:onDismiss:content:)",
+        "func View.lumenSheet(isPresented:title:description:onDismiss:content:) has parameter 3 type change from () -> Swift.Void to Swift.Bool",
+        "func View.lumenSheet(isPresented:title:description:onDismiss:content:) has parameter 4 type change from () -> SheetContent to Swift.Bool"
+      ],
+      "signals": [
+        "lumenSheet",
+        "LumenSheet",
+        "requiredLabel",
+        "panelAccessibilityLabel"
+      ]
+    },
+    {
+      "id": "embedded-mcp-sdk-v2",
+      "kind": "breaking",
+      "currentContract": "Embedded Lumen MCP integrations import SDK v1 server and transport objects.",
+      "replacement": "The embedded server uses SDK v2 server, client and transport packages.",
+      "migration": "Migrate known SDK module paths, update SDK dependencies to compatible v2 packages, rebuild and test the real transport. Other SDK imports require manual review.",
+      "packages": [
+        "@santi020k/lumen-mcp"
+      ],
+      "signals": [
+        "@modelcontextprotocol/sdk/"
+      ],
+      "evidence": [
+        "packages/mcp/src/server.ts"
+      ],
+      "docs": [
+        "docs/migrating-to-lumen.md"
+      ],
+      "tests": [
+        "pnpm run check:mcp-evaluation",
+        "pnpm run check:mcp-package"
+      ]
+    },
+    {
+      "id": "appearance-presets",
+      "kind": "breaking",
+      "currentContract": "Theme palettes and surface dimensions are customized separately in each adapter. Swift surface and theme initializer signatures do not expose appearance or material options.",
+      "replacement": "Canonical Default, Studio and Glass appearances, scoped web tokens, ThemeBuilder dimensions and explicit surface material with native opaque fallbacks.",
+      "migration": "Choose a preset, then override semantic tokens or native appearance values. Glass remains explicit per surface. Rebuild Swift and Compose consumers; Swift initializer references must include the defaulted appearance and material parameters.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements",
+        "@santi020k/lumen-react-native",
+        "@santi020k/lumen-tokens",
+        "@santi020k/lumen-mcp",
+        "LumenUI",
+        "com.santi020k:lumen-compose"
+      ],
+      "evidence": [
+        "docs/appearance-presets.md"
+      ],
+      "docs": [
+        "docs/appearance-presets.md",
+        "docs/migrating-to-lumen.md"
+      ],
+      "tests": [
+        "pnpm run validate",
+        "swift test",
+        "cd packages/compose && ./gradlew test lint apiCheck"
+      ],
+      "swiftApiBreakages": [
+        "constructor LumenCard.init(variant:action:content:) has been removed",
+        "constructor LumenCard.init(variant:padding:radius:action:content:) has been removed",
+        "constructor LumenSurface.init(tone:padding:radius:content:) has been removed",
+        "constructor LumenTheme.init(colors:scheme:) has been removed"
+      ],
+      "signals": [
+        "LumenTheme",
+        "LumenProvider",
+        "ThemeBuilder",
+        "data-lumen-preset",
+        "glass"
+      ]
+    },
+    {
+      "id": "swift-phone-presentation-signature",
+      "kind": "breaking",
+      "currentContract": "The v3 phone initializer does not expose presentation controls.",
+      "replacement": "Defaulted v4 selector, display format, placeholder, flag and size options for existing phone selection behavior.",
+      "migration": "Rebuild Swift consumers and update initializer references for the added defaulted phone presentation parameters.",
+      "packages": [
+        "LumenUI"
+      ],
+      "evidence": [
+        "docs/lumen-4-readiness.md"
+      ],
+      "docs": [
+        "packages/swift/README.md",
+        "docs/lumen-4-readiness.md"
+      ],
+      "tests": [
+        "swift test",
+        "pnpm run check:swift-source-compatibility"
+      ],
+      "swiftApiBreakages": [
+        "constructor LumenPhoneInput.init(_:value:countries:locale:description:errorMessage:showValidationError:invalidNumberMessage:numberLabel:countrySelectorLabel:countryPickerTitle:countrySearchLabel:required:enabled:) has been removed"
+      ],
+      "signals": [
+        "LumenPhoneInput"
+      ]
+    },
+    {
+      "id": "web-content-flow",
+      "kind": "breaking",
+      "currentContract": "Explicit v3 Stack/Grid gaps use a separate scale; cards and reading blocks rely on child margins and clipped overflow.",
+      "replacement": "Canonical web gaps, parent-owned spacing, Card density and visible overflow, responsive Container gutters and trimmed reading-block margins.",
+      "migration": "Map literal web gaps md/lg/xl to group/xl/2xl with lumen migrate v4. Review Card density, compensating margins and clipping; put media clipping in AspectRatio. Native spacing is unchanged.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/content-flow.md"
+      ],
+      "docs": [
+        "docs/migrating-v3-to-v4.md",
+        "docs/content-flow.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "Stack",
+        "Grid",
+        "Card",
+        "Container",
+        "Prose",
+        "Typography"
+      ]
+    },
+    {
+      "id": "web-control-visual-size",
+      "kind": "breaking",
+      "currentContract": "Select, PhoneInput and Segmented use size for visual density; Select also accepts the visual md alias.",
+      "replacement": "visualSize in Astro/React and visual-size in Elements use default, sm or lg. Native input/select size remains numeric. Elements Select uses ui-select-field for its frame and ui-select for its native input and trigger.",
+      "migration": "Run lumen migrate v4 for recognized literals. Change wrapper, spread and dynamic visual size props manually; map Select md to default. Keep numeric size; PhoneInput forwards it through inputProps.size. Button, icon, container and native-platform sizes are unchanged. Update Elements Select host CSS selectors from ui-select to ui-select-field.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/form-controls.md"
+      ],
+      "docs": [
+        "docs/migrating-v3-to-v4.md",
+        "docs/form-controls.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "Select",
+        "PhoneInput",
+        "Segmented",
+        "visualSize",
+        "visual-size"
+      ]
+    },
+    {
+      "id": "web-form-value-ownership",
+      "kind": "breaking",
+      "currentContract": "React Segmented does not retain controlled owner state; React Select popup interactions and resets can diverge from native submission. Elements scalar reconnection, checked defaults and multiple selections can diverge from native forms.",
+      "replacement": "Controlled values remain owner-held; accepted resets restore defaults silently and cancelled resets retain drafts. Each documented user callback fires once. Elements retain listeners and reset defaults after relocation and submit every enabled selected option.",
+      "migration": "Use value/onValueChange or defaultValue deliberately. Listen on Elements hosts and use checked for current state, defaultChecked for the reset baseline. Remove compensating reset or duplicate event handlers after verifying native and external form submission.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/form-controls.md"
+      ],
+      "docs": [
+        "docs/form-controls.md",
+        "docs/migrating-v3-to-v4.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "Segmented",
+        "Select",
+        "NativeSelect",
+        "checked",
+        "defaultChecked",
+        "form.reset"
+      ]
+    },
+    {
+      "id": "web-combobox-focus",
+      "kind": "breaking",
+      "currentContract": "Editable Combobox consumers may assume option buttons receive focus and parent Escape handlers always dismiss.",
+      "replacement": "Input focus remains stable with aria-activedescendant; nested controls consume their own Escape.",
+      "migration": "Update focus assertions and option styling to active-descendant/selected state. Parent handlers must honor defaultPrevented; Enter without an active option retains native form behavior.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/migrating-v3-to-v4.md"
+      ],
+      "docs": [
+        "docs/migrating-v3-to-v4.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "Combobox",
+        "aria-activedescendant",
+        "Escape"
+      ]
+    },
+    {
+      "id": "web-phone-input-identity",
+      "kind": "breaking",
+      "currentContract": "Web PhoneInput id may be treated as a frame identifier.",
+      "replacement": "Astro/React id identifies the number input that receives focus; Elements retains host id and uses input-id for its input.",
+      "migration": "Update labels and DOM queries; use Elements input-id for the input that receives focus. Native phone contracts are covered separately.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/migrating-v3-to-v4.md"
+      ],
+      "docs": [
+        "docs/migrating-v3-to-v4.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "PhoneInput",
+        "input-id"
+      ]
+    },
+    {
+      "id": "web-virtual-list-ranges",
+      "kind": "breaking",
+      "currentContract": "Consumers may interpret virtual-list range endpoints as exclusive.",
+      "replacement": "Fixed-height windows report inclusive endpoints and endIndex -1 for empty lists. Mounted DOM remains the default; opt-in data rendering mounts visible rows and focused neighbors.",
+      "migration": "Update exclusive-end calculations and empty handling. Use stable unique keys and external state for opt-in data rendering; variable-height lists need a different strategy. Existing root imports remain supported; selective component imports are additive.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/virtual-list-data.md"
+      ],
+      "docs": [
+        "docs/migrating-v3-to-v4.md",
+        "docs/virtual-list-data.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "VirtualList",
+        "endIndex"
+      ]
+    },
+    {
+      "id": "web-rich-text-command-ownership",
+      "kind": "breaking",
+      "currentContract": "External editor integrations may execute commands during completion events or fall back to browser commands after failure.",
+      "replacement": "Cancelable ui:editor-command-request owns execution; ui:editor-command reports completion without execution.",
+      "migration": "External engines must preventDefault on the request and set detail.executed synchronously; React can supply commandHandler. Remove completion handlers that execute commands again. Failed external commands do not fall back.",
+      "packages": [
+        "@santi020k/lumen-core",
+        "@santi020k/lumen-astro",
+        "@santi020k/lumen-react",
+        "@santi020k/lumen-elements"
+      ],
+      "evidence": [
+        "docs/migrating-v3-to-v4.md"
+      ],
+      "docs": [
+        "docs/migrating-v3-to-v4.md",
+        "docs/ai-usage.md"
+      ],
+      "tests": [
+        "pnpm run test",
+        "pnpm run test:framework-conformance"
+      ],
+      "signals": [
+        "ui:editor-command-request",
+        "ui:editor-command",
+        "commandHandler"
+      ]
+    }
+  ],
+  "swiftApiBaseline": "v3.0.1",
+  "approval": {
+    "approver": "Santiago Molina (santi020k)",
+    "date": "2026-10-07",
+    "decision": "Publish Lumen 4.0.0 and deploy the coordinated release; deliver playground 1.0.3 for Apple and Android review with current screenshots and listing metadata under the standing authorization, after all checks and reviews pass. Standing authorization is recorded by santi020k in PR #95 comment 6027959606.",
+    "reviewedRevision": "cdb28a38aca0071af35021341bb7fbbefd7730a6",
+    "evidence": [
+      "https://github.com/santi020k/lumen/commit/cdb28a38aca0071af35021341bb7fbbefd7730a6",
+      "https://github.com/santi020k/lumen/pull/95"
+    ]
+  }
+}