layerpro 3.3.0 → 4.0.0

package/README.md

@@ -18,7 +18,7 @@
 ![OXlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
 ![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
 
-LayerPro replaces the browser's native `alert()`, `confirm()`, and `prompt()` with beautiful, fully customizable modals that work everywhere — no more blocking the main thread, no more default browser styling.
+LayerPro replaces the browser's native `alert()`, `confirm()`, and `prompt()` with beautiful, fully customizable modals that work everywhere - no more blocking the main thread, no more default browser styling.
 
 ## Table of Contents
 
@@ -43,12 +43,12 @@ LayerPro replaces the browser's native `alert()`, `confirm()`, and `prompt()` wi
 
 ## Features
 
-- **Zero runtime dependencies** — no jQuery, pure vanilla DOM helpers; `react`/`react-dom` are peer dependencies, only loaded when React bodies are used, powered by [`reattach`](https://npmjs.com/package/reattach)
-- **Multiple modal types** — alert, confirm, prompt, message
-- **Fully customizable** — appearance, behavior, and content
-- **Dockable windows** (taskbar-style) — click a dock icon to restore, focus, or minimize, just like an OS taskbar
-- **Draggable & resizable** — instant, with no transition lag while resizing
-- **CSS-only maximize** — uses `position: fixed` + insets, so it follows the viewport with no JS resize listeners
+- **Zero runtime dependencies** - no jQuery, pure vanilla DOM helpers; `react`/`react-dom` are peer dependencies, only loaded when React bodies are used, powered by [`reattach`](https://npmjs.com/package/reattach)
+- **Multiple modal types** - alert, confirm, prompt, message
+- **Fully customizable** - appearance, behavior, and content
+- **Dockable windows** (taskbar-style) - click a dock icon to restore, focus, or minimize, just like an OS taskbar
+- **Draggable & resizable** - instant, with no transition lag while resizing
+- **CSS-only maximize** - uses `position: fixed` + insets, so it follows the viewport with no JS resize listeners
 - **Fade in/out transitions** for open/close
 - **Full TypeScript support**
 
@@ -72,7 +72,7 @@ Import LayerPro once, in your app's entry point:
 import "layerpro";
 ```
 
-That's it — `alert()`, `confirm()`, `prompt()`, `message()`, and `popup()` are now available globally.
+That's it - `alert()`, `confirm()`, `prompt()`, `message()`, and `popup()` are now available globally.
 
 The `popup` alias is a shorthand for `layerpro.popup`:
 
@@ -120,7 +120,7 @@ popup.open({
 
 ### React Components
 
-LayerPro's React adapter is powered by [`reattach`](https://npmjs.com/package/reattach), a zero-dependency library for mounting React components anywhere in the DOM. It handles root creation, automatic root reuse on duplicate-id reopen, **Context Bridging** across detached roots, and **auto-healing DOM** recovery — all without extra setup.
+LayerPro's React adapter is powered by [`reattach`](https://npmjs.com/package/reattach), a zero-dependency library for mounting React components anywhere in the DOM. It handles root creation, automatic root reuse on duplicate-id reopen, **Context Bridging** across detached roots, and **auto-healing DOM** recovery - all without extra setup.
 
 ```jsx
 popup.open({
@@ -174,7 +174,7 @@ popup.open({
   id: string,             // Unique ID (auto-generated as popup_1, popup_2, ... if omitted)
   body: any,              // Content (text, HTML, or React)
   name: string,           // Modal title
-  icon: string,           // Icon glyph — HTML entity (e.g. "⚠") or HTML string
+  icon: string,           // Icon glyph - HTML entity (e.g. "⚠") or HTML string
 
   // Dimensions (defaults: width 340, height 220; minWidth 340, minHeight 220)
   width: number,
@@ -184,12 +184,13 @@ popup.open({
   maxWidth: number,
   maxHeight: number,
 
-  // Remote content (same-origin only, enforced)
-  source: string,
+   // Remote content (same-origin only, enforced). Rendered as raw HTML;
+   // sanitize server-side if the endpoint is not fully trusted.
+   source: string,
 
-  // React adapter (via reattach)
-  inheritContext: boolean,
-  resilient: boolean,
+   // React adapter (via reattach)
+   inheritContext: boolean,
+   resilient: boolean,
 
   // Position (numbers are px; strings applied as-is, e.g. "10%")
   top: number | string,
@@ -210,8 +211,7 @@ popup.open({
   iconize: boolean,       // allow minimize to dock
   dockable: boolean,      // show an icon in the dock bar
   close: boolean,         // show the close button
-  raised: boolean,        // alias: modal — full-screen overlay that blocks pointer events beneath
-  modal: boolean,         // alias of raised
+   modal: boolean,          // full-screen overlay that blocks pointer events beneath
 
   // Buttons
   buttons: {
@@ -221,44 +221,59 @@ popup.open({
 }
 ```
 
-> **`raised` / `modal`** injects a full-viewport overlay (`popup_raised_<id>`) that intercepts every pointer event — the page underneath becomes unclickable until the popup closes. Both names are accepted.
+> **`modal`** injects a full-viewport overlay (`popup_modal_<id>`) that intercepts every pointer event - the page underneath becomes unclickable until the popup closes. Use `modal: true` for alert/confirm/prompt/message pop ups.
 
-> **Duplicate id** — opening a popup whose `id` already exists brings that window to the front and refreshes its `body`/`buttons` instead of doing nothing.
+> **Duplicate id** - opening a popup whose `id` already exists brings that window to the front and refreshes its `body`/`buttons` instead of doing nothing.
 
-## Global Overrides
+## Global Overrides (Opt-in in 4.0)
 
-Importing LayerPro replaces the native `alert`, `confirm`, and `prompt` globals with callback-based versions, and adds a `message` global:
+In 4.0, `import "layerpro"` no longer overrides the native `alert`, `confirm`,
+and `prompt` globals. The library exposes its own methods on `window.layerpro`
+and provides Promise-based alternatives. To override the browser globals, use
+the **explicit entrypoint**:
 
 ```javascript
+// Default entry - library installed, globals NOT overridden
 import "layerpro";
 
-alert("Hello World!");              // LayerPro alert
-confirm("Sure?", yes => {...});     // LayerPro confirm (callback, not a boolean return!)
-prompt("Name?", name => {...});     // LayerPro prompt (callback, not a string return!)
-message("Done!");                   // LayerPro message
+layerpro.alert("Hello World!");              // Promise<void>
+const confirmed = await layerpro.confirm("Sure?");   // Promise<boolean>
+const name = await layerpro.prompt("Name?");          // Promise<string>
+layerpro.message("Done!");                            // Promise<void>
 ```
 
-> **⚠️ Important:** the overridden `confirm()` no longer returns a `boolean`, and `prompt()` no longer returns a `string` — they are callback-based and return `undefined`. Any third-party code that does `if (confirm("..."))` will silently fall into the falsy branch. If your codebase depends on native synchronous return values, call **`layerpro.noGlobals()`** right after importing LayerPro to restore the originals:
->
-> ```javascript
-> import "layerpro";
-> layerpro.noGlobals();   // restores native alert/confirm/prompt, drops `message`
-> ```
+### Override browser globals (opt-in)
+
+If you need `window.alert` / `window.confirm` / `window.prompt` / `window.message`
+replaced with LayerPro's Promise-based versions, import the global entrypoint:
+
+```javascript
+import "layerpro/global";  // installs Promise-based overrides on window
+
+// These now return Promises instead of native values:
+await alert("Hello World!");              // Promise<void>
+const ok = await confirm("Sure?");        // Promise<boolean>
+const val = await prompt("Name?");        // Promise<string>
+```
+
+> **⚠️ Important:** overridden `confirm()` returns `Promise<boolean>`, not a
+> synchronous `boolean`. Code that does `if (confirm("..."))` must be
+> `await`-ed. Only use `layerpro/global` if you control all call sites.
 
 ## Methods
 
 | Method | Description |
 |--------|-------------|
-| `popup.open(props)` | Open a modal; returns the props. Re-opens a same-id window to front and refreshes its body. |
+| `popup.open(props)` | Open a modal; returns `Promise<GenLayerProps>` - resolves when the popup closes. |
 | `popup.close(id)` | Close (and unmount) a modal. |
 | `popup.center(id, offset?)` | Center a modal in the viewport; optional pixel offset. |
 | `popup.maximize(props)` | Toggle maximize (pure CSS). |
 | `popup.iconize(id)` | Toggle minimize to the dock. |
 | `popup.index(id)` | Bring a modal to the front (select). |
-| `popup.zIndex()` | Get the next z-index counter value. |
 | `popup.movable(props)` | Enable dragging. |
 | `popup.resizable(props)` | Enable resizing. |
-| `layerpro.noGlobals()` | Restore native `alert`/`confirm`/`prompt`; remove `message`. |
+| `layerpro.installGlobals()` | Override `window.alert/confirm/prompt/message` with LayerPro's Promise-based versions. |
+| `layerpro.config(opts)` | Runtime config. Currently supports `{ nonce: string }` for CSP; sets `window.__layerproNonce` consumed by the injected `<style>`. Call before importing LayerPro for the nonce to be present at injection. |
 
 ## Styling & z-index
 
@@ -280,25 +295,15 @@ The title bar, window surface, internal area, and body all read from CSS custom
 | `--window-border-radius` | popup border radius |
 | `--internal-background` | body wrapper |
 | `--body-color` | body text color |
-| `--raised-background` | modal overlay |
+ | `--modal-background` | modal overlay |
 | `--popup-z-index` | base z-index for the stack |
 
 ## Security
 
-- **Same-origin fetch guard** — the `source` prop only accepts same-origin URLs; cross-origin requests are rejected before any network call is made, preventing SSRF and data exfiltration.
-- **HTML escaping** — all user-provided text content (button labels, body content, titles) is automatically escaped via `escapeHtml()` to prevent XSS.
-- **CSP-friendly** — no inline scripts or `eval()` are used. React components are rendered via `reattach.mount()` (backed by `createRoot()`).
-- **Opt-out of global overrides** — call `layerpro.noGlobals()` after import to restore native `alert`, `confirm`, `prompt`, and remove the `message` global if your codebase depends on synchronous return values.
-
-## Browser Support
-
-Chrome 80+ • Firefox 75+ • Safari 13+ • Edge 80+
-
-## Contributing
-
-LayerPro's source is currently private, but contributions and discussion are welcome. Get in touch:
-
-- **Dario Passariello** — https://dario.passariello.ca/ — dariopassariello@gmail.com
+- **Same-origin fetch guard** - the `source` prop only accepts same-origin URLs; cross-origin requests are rejected before any network call is made, preventing SSRF and data exfiltration.
+- **HTML escaping** - all user-provided text content (button labels, body content, titles) is automatically escaped via `escapeHtml()` to prevent XSS.
+- **CSP-friendly** - no inline scripts or `eval()` are used. React components are rendered via `reattach.mount()` (backed by `createRoot()`). For strict CSP environments, the injected stylesheet auto-detects the nonce from `window.__layerproNonce`, existing `<style>`/`<script>` elements, or `document.body.dataset.nonce`. Alternatively, import the stylesheet as a static file via `import 'layerpro/style.css'` to avoid inline style injection entirely. Use `layerpro.config({ nonce })` for explicit nonce control.
+- **No global side effects** - `import 'layerpro'` does NOT override `window.alert`/`confirm`/`prompt`. Use `import 'layerpro/global'` or `layerpro.installGlobals()` to opt in to the global overrides.
 
 ## License
 

package/SECURITY-HARDENING.md

@@ -0,0 +1,265 @@
+# Security Hardening Guide
+
+This document is a security reference for LayerPro maintainers and consumers.
+It documents every threat surface in the library, the defense-in-depth controls
+that mitigate it, and the residual risks that must be managed at the application
+level.
+
+---
+
+## 1. Threat Surface Summary
+
+| Threat | Vector | Mitigation | Residual Risk |
+|--------|--------|------------|---------------|
+| Global override side effects | `import 'layerpro/global'` rewrites `window.alert/confirm/prompt` | Globals are opt-in (not auto-applied) in 4.0; `layerpro.installGlobals()` for programmatic opt-in; native globals untouched by default | Consumers who import `layerpro/global` accept Promise-based globals |
+| XSS via popup body | `body: '<script>...'` or `buttons.confirm.text: '<img onerror=...>'` | `escapeHtml()` on all string bodies, button labels, names, icons | Does **not** protect against stored XSS from same-origin `source` (see §5) |
+| SSRF via `source` prop | `source: 'https://evil.example.com/...'` | Same-origin URL check (`url.origin !== window.location.origin`) + `fetch` mode `same-origin` | Same-origin XSS (server compromise or stored content on own domain) is still possible |
+| CSP bypass via inline `<style>` | CSS injected via `document.head.appendChild(<style>)` | Nonce auto-detection (`window.__layerproNonce`, `<style[nonce]>`, `<script[nonce]>`, `document.body.dataset.nonce`) | If no nonce is detectable, strict CSP will silently drop the stylesheet |
+| React DOM injection | `body: <Component />` executes arbitrary component code | React adapter loaded lazily via dynamic `import('layerpro/react')` - `react-dom` is never in the core bundle | Consumer is fully responsible for the React components they pass |
+| Prototype pollution | `setProps` iterates `Reflect.ownKeys` and reassigns descriptors | `setProps` only operates on the frozen `layerpro` object (non-enumerable, non-configurable, non-writable) | Low - `layerpro` is frozen in `index.ts:21` |
+
+---
+
+## 2. CSP (Content Security Policy) Support
+
+LayerPro supports three strategies for strict CSP environments, in order
+of preference:
+
+### Strategy A - Static stylesheet import (recommended)
+
+```js
+import 'layerpro/style.css'
+```
+
+This serves the CSS as a static file under `style-src 'self'`. No inline
+`<style>` element is created at all, so no nonce or hash is needed.
+
+In `package.json`:
+
+```json
+{
+  "exports": {
+    "./style.css": "./dist/index.css"
+  },
+  "files": ["dist/index.css", "..."]
+}
+```
+
+### Strategy B - Nonce auto-detection
+
+When the CSS-in-JS injection path is used (i.e., `import 'layerpro'` without
+the static stylesheet), the injected `<style>` element reads the nonce from:
+
+1. `window.__layerproNonce` - set explicitly via `layerpro.config({ nonce })`
+2. Any existing `<style>` or `<script>` element with a `nonce` attribute
+3. `document.body.dataset.nonce`
+
+This is implemented in `tsup.plugin.injectCss.ts`:
+
+```js
+const n = window.__layerproNonce
+  || window.layerpro?.nonce
+  || document.querySelector('style[nonce],script[nonce]')?.nonce
+  || document.body?.dataset?.nonce
+if (n) s.setAttribute('nonce', n)
+```
+
+Under a strict `style-src` policy with no detectable nonce, the stylesheet
+is **silently dropped** (the browser rejects it). Popups will render unstyled.
+
+### Strategy C - Explicit nonce configuration
+
+```js
+// Call BEFORE importing LayerPro so the nonce is set at injection time
+window.__layerproNonce = 'your-base64-nonce-here'
+// OR
+import 'layerpro'
+layerpro.config({ nonce: 'your-base64-nonce-here' })
+```
+
+> **Important**: `layerpro.config({ nonce })` must be called **before** the
+> CSS is first injected (i.e., before `import 'layerpro'`). If the module
+> was already imported, the nonce will not be retroactively applied to the
+> already-injected `<style>`.
+
+---
+
+## 3. Global Override Security Model
+
+### Risk (legacy 3.x pattern)
+
+In LayerPro 3.x, `import 'layerpro'` unconditionally replaced
+`window.alert`, `window.confirm`, `window.prompt`, and added `window.message`.
+The overridden versions were **callback-based and asynchronous** - they did not
+return native values:
+
+```js
+import 'layerpro'
+
+confirm('Are you sure?') // returns undefined, NOT a boolean
+if (confirm('Proceed?')) { ... } // ALWAYS falsey - silently breaks!
+```
+
+Any third-party code in your `node_modules` that relied on synchronous return
+values would break **silently** (no error, no warning, just the falsy branch).
+
+### 4.0 Mitigation: opt-in globals
+
+LayerPro 4.0 **removes the auto-override**. The main entry (`import 'layerpro'`)
+no longer touches browser globals at all. To opt in to global overrides, use:
+
+```js
+import 'layerpro/global'   // explicitly overrides window.alert/confirm/prompt/message
+
+const confirmed = await confirm('Are you sure?')  // Promise<boolean>
+```
+
+Or programmatically:
+
+```js
+import 'layerpro'
+layerpro.installGlobals()  // same effect, explicit call
+```
+
+### Recommendation
+
+In 4.0, simply **do not import `layerpro/global`** if you need the native
+synchronous `alert`/`confirm`/`prompt`. Use the Promise-based methods on the
+`layerpro` object directly instead:
+
+```js
+import 'layerpro'
+
+const confirmed = await layerpro.confirm('Are you sure?')
+```
+
+---
+
+## 4. XSS Prevention
+
+All user-provided string content is escaped via `escapeHtml()` (regex-based
+replacement of `& < > " '` → HTML entities) before being inserted into the DOM:
+
+- **Popup body (text/HTML strings)**: `core/genLayer.ts:escapeHtml()`
+- **Button labels**: `core/genLayer.ts:escapeHtml()` (confirm/cancel text)
+- **Popup name/icon**: `core/genLayer.ts:escapeHtml()`
+- **`alert()`/`confirm()`/`prompt()`/`message()` bodies**: `core/message.ts:escapeHtml()`
+
+This is **not** a sanitization library - it does not allow any HTML through.
+Raw HTML rendering is deliberately not supported for string bodies. If you
+need raw HTML, use the React adapter with a component that explicitly
+renders `dangerouslySetInnerHTML`.
+
+---
+
+## 5. `source` Prop (Remote Content Loading)
+
+The `source` prop fetches same-origin HTML and injects it into the popup body.
+
+### Same-origin enforcement
+
+- `core/genLayer.ts:loadSource()` constructs a `URL` and checks
+  `url.origin !== window.location.origin`
+- The `fetch()` call also uses `mode: 'same-origin'` as a second layer
+- The same-origin guard is the **primary defense** against SSRF
+
+### What is rendered
+
+Remote HTML is injected as **raw, unescaped HTML** (as of 3.4.1 - previously
+it was double-escaped, rendering all tags as visible text). This means:
+
+- `<p>Hello</p>` renders as a real paragraph (not visible tags)
+- `<script>` tags in the response are **executed** when the HTML is parsed
+- Event handlers (`onclick="..."`) in the response are **activated**
+
+### Consumer responsibility
+
+The same-origin guard protects against cross-origin SSRF, but **not** against
+same-origin XSS. If an attacker can inject malicious HTML into an endpoint
+on your own domain (stored XSS), the `source` prop will render it.
+
+**Always sanitize server-side content before serving it as a `source` URL.**
+
+### Abort safety
+
+An `AbortController` is associated with each `source` fetch and is aborted
+when the popup closes (`layerpro.popup.abortSource(id)`), preventing
+callbacks from targeting a destroyed layer.
+
+---
+
+## 6. React Adapter Isolation
+
+The React adapter (`layerpro/react`) is loaded via dynamic `import('layerpro/react')`
+only when a React element is passed as the `body` prop:
+
+- `react-dom` is **never** imported in the core bundle (verified by `verify-fixes.mjs`)
+- The adapter is a separate entry point declared in `package.json` `exports`
+- `reattach` is bundled **inside** the adapter, not as a separate dependency
+- The adapter externalizes only `react` and `react-dom` as peer dependencies
+
+This ensures consumers who don't use React bodies never load `react-dom`.
+
+### Risk
+
+The `import('layerpro/react')` bare-specifier requires a bundler that
+understands the `exports` field in `package.json`. In plain `<script type="module">`
+environments or old bundlers, this dynamic import will fail. The failure is
+caught and logged:
+
+```js
+import('layerpro/react').then(adapter => { ... }).catch(error => {
+  console.error('LayerPro Error: React adapter failed to load.')
+  console.debug(error)
+})
+```
+
+No error is surfaced to the user - the popup renders with an empty body.
+
+---
+
+## 7. Accessibility & Security Interaction
+
+LayerPro renders popups with the following ARIA attributes (as of 3.4.1):
+
+- `role="dialog"` on the popup window container
+- `aria-modal="true"` on modal popups
+- `aria-label` (from `props.name`) or `aria-labelledby` if a named title exists
+- `aria-hidden="true"` on all `<body>` children except `#popup` while a modal is open
+- `tabindex="-1"` on the popup window (focusable via script)
+
+### Focus management
+
+- The currently focused element is saved when a popup opens
+- Focus is moved into the popup via `requestAnimationFrame` + `.focus()`
+- A `Tab` key listener traps focus within the popup container (cycles to
+  first/last focusable element)
+- On close, focus is restored to the previously active element and
+  `aria-hidden` is removed from page content
+
+### Limitations
+
+- This is a **lightweight** focus trap (Tab key only). It does not handle
+  screen reader virtual cursor navigation, nested modals, or `inert` polyfill.
+- `aria-hidden` on page content is not equivalent to `inert` - focus can
+  still technically reach page elements via direct `.focus()` calls from
+  application code.
+
+---
+
+## 8. Build-time Security
+
+- `tsup.plugin.injectCss.ts` injects CSS at build time with nonce support
+- `tsup.plugin.copyStatic.ts` rewrites the dist `package.json` exports map
+- `tsup.plugin.types.ts` generates `react.d.ts` and patches `index.d.ts`
+  with a `dphelper` reference (tsc strips `/// <reference>` from `.ts` files)
+- `react.d.ts` is included in the npm `files` array so `import layerpro/react`
+  resolves types under `moduleResolution: bundler`
+
+---
+
+## 9. Reporting
+
+If you have a potential security vulnerability to report, please email
+[@passariello](https://github.com/passariello) or see
+<https://dario.passariello.ca/contact/>.

package/SECURITY.md

@@ -1,3 +1,11 @@
 # Security
 
 Please email [@passariello](https://github.com/passariello) or see <https://dario.passariello.ca/contact/> if you have a potential security vulnerability to report.
+
+## Source feature (same-origin fetch)
+
+The `source` prop fetches HTML from a same-origin URL and renders it as-is.
+The same-origin guard prevents SSRF to other hosts, but the fetched markup is
+NOT sanitized by LayerPro. Any same-origin endpoint used as a `source` must
+sanitize its output server-side. Consumers needing client-side sanitization
+should pass a React element in `body` instead.