flet-box 1.0.3 → 1.0.5

package/docs/widget/Tooltip.md

@@ -0,0 +1,145 @@
+# Tooltip
+
+Wraps a child widget and shows a labeled overlay bubble on hover or focus. The bubble is rendered as a portal on document.body so it is never clipped.
+
+## When to use it
+
+Use it to explain icons, buttons, or dense fields that cannot fit a visible label.
+
+## Quick start
+
+```javascript
+import { Button, Tooltip, clipboard } from "flet-box";
+
+const tip = Tooltip({
+  text: "Copy to clipboard",
+  child: Button({ text: "Copy" }),
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `text` | `string` | Visible text content. |
+| `child` | `Widget` | A single child widget. Alias: `children` for a list. |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | CSS `position` value, or `stack` for centered stacking. |
+| `delay` | `number` | Delay before the animation starts, in milliseconds. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `textColor` | `Color` | Color of the button label. |
+| `fontSize` | `number` | Size of the font. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `offset` | `number` | The `offset` value for the widget. |
+| `showArrow` | `boolean` | Controls whether the arrow is shown. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `maxWidth` | `number` | Maximum width the widget may grow to. |
+| `textAlign` | `'left' \| 'center' \| 'right'` | The `textAlign` value for the widget. |
+| `zIndex` | `number` | Index used for the z. |
+| `animationDuration` | `number` | Duration for the animation, in milliseconds. |
+| `arrowSize` | `number` | Size of the arrow. |
+| `borderColor` | `Color` | Color used for the border. |
+| `borderWidth` | `number` | Width of the border. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Icon, Tooltip } from "flet-box";
+
+const tip = Tooltip({
+  text: "Adds the item to your cart",
+  position: "bottom",
+  delay: 150,
+  child: Icon({ name: "shopping_cart" }),
+});
+```
+
+### Full
+
+```javascript
+import { Button, Tooltip, rgba } from "flet-box";
+
+const tip = Tooltip({
+  text: "Only visible to workspace admins",
+  child: Button({ text: "Share", variant: "outlined" }),
+  position: "right",
+  delay: 300,
+  offset: 12,
+  maxWidth: 240,
+  bgColor: "#111827",
+  textColor: "#f9fafb",
+  showArrow: true,
+  textAlign: "left",
+  borderRadius: 8,
+  shadow: "0 4px 12px rgba(0,0,0,0.25)",
+  animationDuration: 180,
+});
+```
+
+## Tips
+
+- Attach it to any widget via child; the tooltip is a separate portal, so overflow
+- hidden ancestors do not cut it off.
+- delay controls how long the pointer must rest before the tooltip appears; lower it
+- for dense toolbars, raise it for error-prone hints.
+- The bubble is clamped to the viewport edges, so top/left placements can sit slightly
+- inside the window bounds.
+
+## Accessibility
+
+- The wrapped child keeps its focus handlers, so keyboard users tabbing onto it get
+- the same tooltip as mouse hover.
+
+## Behavior
+
+- The tooltip hides itself on window scroll or resize and removes its body portal plus
+- listeners on unmount.
+- The wrapped child gains showTooltip, hideTooltip, updateContent, and updatePosition
+- helpers for imperative control.
+
+## Related widgets
+
+- [Button](Button.md)
+- [Icon](Icon.md)
+- [Text](Text.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [SnackBar](SnackBar.md)
+- **Next:** [ProgressBar](ProgressBar.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 4 · Feedback and overlays** (5 of 10).

package/docs/widget/TreeView.md

@@ -0,0 +1,176 @@
+# TreeView
+
+TreeView renders a collapsible hierarchy from nodes, each with an id, label, optional icon, badge and children. It supports expand/collapse, selection and nested navigation.
+
+## When to use it
+
+Use it for file explorers, category menus or any nested set of items the user drills into.
+
+## Quick start
+
+```javascript
+import { TreeView } from "flet-box";
+
+const tree = TreeView({
+  nodes: [
+    { id: "src", label: "src" },
+  ],
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `nodes` | `Array<{` | Tree nodes, each with `id`, `label`, and optional `children`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `label` | `string` | Label or caption shown near the control. |
+| `icon` | `string` | Name of the icon to render. |
+| `iconColor` | `Color` | Color of the field icons. |
+| `children` | `any[]` | An array of child widgets. Alias: `child` for a single child. |
+| `badge` | `string \| number` | The `badge` value for the widget. |
+| `onSelect` | `(node: any) => void` | Fired when the widget or an option is selected. |
+| `onToggle` | `(nodeId: string, expanded: boolean) => void` | Fired with the new toggled state. |
+| `expandedNodes` | `string[]` | Ids of nodes that start expanded. |
+| `indent` | `number` | Indentation depth used when printing nested structures. |
+| `showIcons` | `boolean` | Controls whether the icons is shown. |
+| `folderIcon` | `string` | Icon for the folder. |
+| `folderOpenIcon` | `string` | Icon for the folder open. |
+| `fileIcon` | `string` | Icon for the file. |
+| `expandIcon` | `string` | Icon for the expand. |
+| `collapseIcon` | `string` | Icon for the collapse. |
+| `defaultExpanded` | `boolean` | Expands top-level nodes by default. |
+| `selectable` | `boolean` | Lets the user select a tree node. |
+| `selectedNodeId` | `string \| null` | Id of the currently selected node. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `hoverBgColor` | `Color` | Background color for the hover. |
+| `selectedBgColor` | `Color` | Background color for the selected. |
+| `textColor` | `Color` | Color of the button label. |
+| `selectedTextColor` | `Color` | Color used for the selected text. |
+| `iconColor` | `Color` | Color of the field icons. |
+| `folderIconColor` | `Color` | Color used for the folder icon. |
+| `borderColor` | `Color` | Color used for the border. |
+| `nodePadding` | `Padding` | Padding for the node. |
+| `nodeGap` | `number` | Space for the node. |
+| `childrenGap` | `number` | Space for the children. |
+| `borderRadius` | `number` | Rounds the corners of the widget. |
+| `fontSize` | `number` | Size of the font. |
+| `iconSize` | `number` | Size of the field icons. |
+| `transitionDuration` | `string` | Duration for the transition, in milliseconds. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { TreeView } from "flet-box";
+
+const tree = TreeView({
+  nodes: [
+    {
+      id: "src",
+      label: "src",
+      children: [
+        { id: "app", label: "app.js" },
+        { id: "router", label: "Router.js" },
+      ],
+    },
+  ],
+  showIcons: true,
+  onSelect: (node) => console.log(node.id),
+});
+```
+
+### Full
+
+```javascript
+import { TreeView } from "flet-box";
+
+const tree = TreeView({
+  nodes: [
+    {
+      id: "src",
+      label: "src",
+      icon: "folder",
+      children: [
+        { id: "app", label: "app.js", icon: "description" },
+        { id: "router", label: "Router.js", badge: 2 },
+      ],
+    },
+  ],
+  expandedNodes: ["src"],
+  defaultExpanded: true,
+  selectable: true,
+  showIcons: true,
+  selectedNodeId: "app",
+  indent: 20,
+  nodeGap: 4,
+  childrenGap: 4,
+  fontSize: 14,
+  transitionDuration: "200ms",
+  hoverBgColor: "#f1f5f9",
+  selectedBgColor: "#dbeafe",
+  onToggle: (nodeId, expanded) => console.log(nodeId, expanded),
+  onSelect: (node) => console.log(node.id),
+});
+```
+
+## Tips
+
+- Give every node a stable unique id; expandedNodes and selectedNodeId reference those ids.
+- Set selectable to false for navigation trees where tapping should only toggle groups.
+- Use defaultExpanded to open first-level groups on first render.
+
+## Accessibility
+
+- Expose meaningful label text and do not rely only on icons to describe a node.
+- Keep onSelect behavior predictable so keyboard users understand what activation does.
+
+## Behavior
+
+- Nodes toggle locally and report expansion through onToggle with the nodeId and expanded flag.
+- Selection is reported through onSelect as the node object and can be controlled with selectedNodeId.
+
+## Related widgets
+
+- [ListView](ListView.md)
+- [ListTile](ListTile.md)
+- [Accordion](Accordion.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Accordion](Accordion.md)
+- **Next:** [Carousel](Carousel.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 5 · Navigation and flows** (3 of 5).

package/docs/widget/Video.md

@@ -0,0 +1,127 @@
+# Video
+
+Renders a native <video> element with proper media attributes and a convenient playback API. Helpers for play, pause, stop, restart, and volume.
+
+## When to use it
+
+Use it to embed a clip, trailer, ambient background video, or lecture recording.
+
+## Quick start
+
+```javascript
+import { Video } from "flet-box";
+
+const clip = Video({
+  src: "/media/intro.mp4",
+});
+```
+
+> The prop table is generated from `src/index.d.ts`; the examples use only documented props.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `src` | `string` | Resource URL for the image, audio, or video. |
+| `width` | `number \| string` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `number \| string` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `autoplay` | `boolean` | Starts playback automatically. |
+| `controls` | `boolean` | Shows the native media playback controls. |
+| `loop` | `boolean` | Restarts playback when it reaches the end. |
+| `muted` | `boolean` | Starts playback with the audio muted. |
+| `poster` | `string` | Image shown before a video starts playing. |
+| `ref` | `(video: HTMLVideoElement) => void` | Callback that receives the underlying DOM node. |
+
+### Common props
+
+Every widget also accepts these shared props — see [common props](COMMON_PROPS.md) for the full rules and aliases.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
+| `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
+| `size` | `Size` | Overall size preset or pixel value, depending on the widget. |
+| `padding` | `Padding` | Space inside the widget, between its content and its border. |
+| `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
+| `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `color` | `Color` | Foreground color, usually the text or icon color. |
+| `borderRadius` | `number \| string` | Rounds the corners of the widget. |
+| `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
+| `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
+| `visible` | `boolean` | Whether the widget is rendered and visible. |
+| `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
+| `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
+| `onClick` | `(widget: Widget) => void` | Callback fired when the widget is clicked. Alias: `onPress`. |
+| `id` | `string` | DOM `id` for the rendered element. |
+| `className` | `string` | CSS class names applied to the rendered element. |
+| `ref` | `(widget: Widget) => void` | Callback that receives the underlying DOM node. |
+| `disableTransform` | `boolean` | Disables the default press/scale transform animation. |
+
+## Examples
+
+### Everyday
+
+```javascript
+import { Video } from "flet-box";
+
+const clip = Video({
+  src: "/media/intro.mp4",
+  controls: true,
+  width: "100%",
+  height: 360,
+  poster: "/media/intro-poster.jpg",
+});
+```
+
+### Full
+
+```javascript
+import { Video } from "flet-box";
+
+const clip = Video({
+  src: "/media/demo.mp4",
+  width: "100%",
+  height: 480,
+  controls: true,
+  autoplay: false,
+  loop: true,
+  muted: true,
+  poster: "/media/demo-poster.jpg",
+  ref: (video) => video.playVideo(),
+});
+```
+
+## Tips
+
+- controls, loop, muted, and autoplay are set as element properties, not CSS, so they
+- work even though they look like styling props.
+- Browsers block autoplay with sound; pair autoplay: true with muted: true for a
+- reliable ambient loop.
+- The ref callback receives the element extended with playVideo, pauseVideo, stop,
+- restart, volumeUp, and muteVideo helpers.
+
+## Accessibility
+
+- Keep controls: true so keyboard and screen-reader users can operate playback.
+
+## Behavior
+
+- playVideo swallows the browser's autoplay rejection instead of throwing, so it is
+- safe to call from a click handler.
+
+## Related widgets
+
+- [Audio](Audio.md)
+- [Image](Image.md)
+- [Card](Card.md)
+
+---
+
+## Continue reading
+
+- **Previous:** [Audio](Audio.md)
+- **Next:** [DraggBox](DraggBox.md)
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter 7 · Media and drag & drop** (2 of 4).

package/docs/widget/_template.md

@@ -0,0 +1,61 @@
+# WidgetName
+
+## Overview
+
+Explain what the widget is for in one or two sentences.
+
+## When to use it
+
+Describe the situation in which you reach for this widget.
+
+## Quick start
+
+```javascript
+import { WidgetName } from "flet-box";
+
+const example = WidgetName({
+  // the smallest useful call
+});
+```
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `propName` | `Type` | What the prop does. |
+
+## Examples
+
+### Everyday
+
+Show the most common combination of props.
+
+### Full
+
+Show advanced layout, styling and events.
+
+## Tips
+
+- Practical, widget-specific advice.
+
+## Accessibility
+
+- Keyboard and screen-reader considerations.
+
+## Behavior
+
+- Layout, interaction and re-render notes.
+
+## Related widgets
+
+- [Container](Container.md)
+
+---
+
+## Continue reading
+
+- **Previous:** ...
+- **Next:** ...
+- **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
+
+You are reading **Chapter N · Title** (i of m).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,8 @@
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
     "release": "node bin/cli.js release",
-    "test": "node scripts/check-widgets.mjs"
+    "test": "node scripts/check-widgets.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-router-base.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
+    "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [
     "fletbox",
@@ -51,6 +52,7 @@
   "files": [
     "bin/",
     "src/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],

package/src/animations/AnimatedBox.js

@@ -334,6 +334,24 @@ const interpolateGradient = (gradient1, gradient2, t) => {
  * @param {string} keyframes - The keyframe body (everything inside `@keyframes name { … }`).
  * @returns {void}
  */
+/**
+ * Stable hash of a keyframe body, used as the generated animation name so that
+ * identical keyframes are injected only once.
+ *
+ * @param {string} keyframes
+ * @returns {string}
+ */
+const hashKeyframes = (keyframes) => {
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  for (let i = 0; i < keyframes.length; i++) {
+    const c = keyframes.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = Math.imul(h2 + c, 0x85ebca6b) ^ (h2 >>> 13);
+  }
+  return (h1 >>> 0).toString(36) + (h2 >>> 0).toString(36);
+};
+
 const injectKeyframes = (name, keyframes) => {
   if (injectedKeyframes.has(name)) return;
   const style = document.createElement("style");
@@ -365,6 +383,15 @@ const generateKeyframes = (animations) => {
       const effect = effectMap[anim.effect] || anim.effect;
       const { from, to, reverse = true } = anim;
 
+      // A descriptor without `from`/`to` is malformed. Skip it with a warning
+      // rather than throwing a TypeError out of the caller's entire render.
+      if (from === undefined || to === undefined) {
+        console.warn(
+          `⚠️ [AnimatedBox] Skipping animation "${anim.effect}": "from" and "to" are required.`,
+        );
+        return;
+      }
+
       let value;
       let color;
 
@@ -589,8 +616,12 @@ export const AnimatedBox = ({
       child.style.background = firstAnim.from;
     }
 
-    const name = `anim-${Date.now()}-${animationCounter++}`;
     const keyframes = generateKeyframes(animations);
+    // The name is derived from the keyframe body so identical animations reuse a
+    // single <style>. A per-call unique name (`Date.now()`) made the dedupe check
+    // in `injectKeyframes` dead code: every call appended a permanent <style> to
+    // document.head, and AnimatedText calls this once per letter.
+    const name = `anim-${hashKeyframes(keyframes)}`;
     injectKeyframes(name, keyframes);
 
     const duration = animations[0]?.duration || 500;

package/src/animations/AnimatedText.js

@@ -39,9 +39,13 @@ export const AnimatedText = ({
   if (!child) return null;
   if (!animations || animations.length === 0) return child;
 
-  // Extract text content and props from the original Text widget
-  const originalText = child._props?.text || child.textContent || "";
-  const originalProps = { ...(child._props || {}) };
+  // Extract text content and props from the original Text widget. The factory
+  // stores props in `_originalProps`; `_props` is never assigned by anything, so
+  // reading it here silently dropped every style (font, size, colour) and the
+  // documented per-letter inheritance never happened.
+  const sourceProps = child._originalProps || child._props || {};
+  const originalText = sourceProps.text || child.textContent || "";
+  const originalProps = { ...sourceProps };
   // Ensure no background animation styles bleed into individual letter widgets
   delete originalProps.animations;
 

package/src/animations/MatrixRain.js

@@ -52,6 +52,11 @@ export const MatrixRain = (props = {}) => {
   let drops = [];
   let columns = 0;
   let resizeObserver = null;
+  let observedParent = null;
+  // The canvas is returned to the caller and appended afterwards, so it is NOT
+  // connected when the animation starts. `wasConnected` tracks that first mount
+  // so the loop can stop when the canvas is later removed from the document.
+  let wasConnected = false;
 
   /**
    * Determines the canvas dimensions based on positioning mode.
@@ -84,14 +89,17 @@ export const MatrixRain = (props = {}) => {
    */
   const resizeCanvas = () => {
     if (!canvas) return;
-    if (
-      position === "absolute" &&
-      !resizeObserver &&
-      typeof ResizeObserver !== "undefined" &&
-      canvas.parentElement
-    ) {
-      resizeObserver = new ResizeObserver(resizeCanvas);
-      resizeObserver.observe(canvas.parentElement);
+    // The canvas is returned to the caller and appended afterwards, so on the
+    // first call there is no parent yet. Create the observer once and (re)attach
+    // it whenever the canvas ends up living in a different parent.
+    if (position === "absolute" && typeof ResizeObserver !== "undefined") {
+      if (!resizeObserver) resizeObserver = new ResizeObserver(resizeCanvas);
+      const parent = canvas.parentElement;
+      if (parent && observedParent !== parent) {
+        if (observedParent) resizeObserver.unobserve(observedParent);
+        resizeObserver.observe(parent);
+        observedParent = parent;
+      }
     }
     const { width, height } = getCanvasSize();
     canvas.width = width;
@@ -154,6 +162,25 @@ export const MatrixRain = (props = {}) => {
   const draw = () => {
     if (!ctx || !canvas) return;
 
+    // The canvas is handed back to the caller and appended afterwards, so it is
+    // disconnected while the animation starts. Once it HAS been mounted, a
+    // disconnect means it was removed from the document — stop there.
+    //
+    // Nothing else covers that path: `runApp`'s teardownTree and Scaffold's
+    // observer call `_cleanup()`, but the lifecycle observer in
+    // `src/widget-factory/lifecycle.js` only fires `onUnmount`, and a raw canvas
+    // has no such hook. Without this guard the loop would keep re-arming at
+    // 60fps painting into a detached canvas, forever.
+    if (canvas.isConnected) {
+      if (!wasConnected) {
+        wasConnected = true;
+        resizeCanvas(); // size to the real parent and attach the observer
+      }
+    } else if (wasConnected) {
+      cleanup();
+      return;
+    }
+
     // Semi-transparent black overlay produces the trailing-fade effect
     ctx.fillStyle = `rgba(0, 0, 0, ${fadeAmount})`;
     ctx.fillRect(0, 0, canvas.width, canvas.height);
@@ -188,10 +215,8 @@ export const MatrixRain = (props = {}) => {
   };
 
   window.addEventListener("resize", handleResize);
-  if (position === "absolute" && typeof ResizeObserver !== "undefined") {
-    resizeObserver = new ResizeObserver(resizeCanvas);
-    if (canvas.parentElement) resizeObserver.observe(canvas.parentElement);
-  }
+  // NOTE: the parent ResizeObserver is attached from `resizeCanvas()` (see
+  // above), because the canvas has no parent until the caller appends it.
 
   /**
    * Stops the animation loop, removes event listeners, disconnects the