@forgeax/app-shell 0.3.0 → 0.4.0

package/README.md

@@ -33,6 +33,25 @@ registry.register(createShellContribution({
 }));
 ```
 
+React shell and slot-diagnostic primitives are available from the explicit
+React entry point:
+
+```tsx
+import {
+  ShellSlot,
+  SlotDebugOverlay,
+  isSlotDebugEnabled,
+} from '@forgeax/app-shell/react';
+
+export function ProductShell() {
+  return (
+    <ShellSlot as="main" name="Workspace">
+      {isSlotDebugEnabled() ? <SlotDebugOverlay /> : null}
+    </ShellSlot>
+  );
+}
+```
+
 ## Ownership boundary
 
 | Package | Owns |

package/dist/react.d.ts

@@ -1,4 +1,11 @@
-import { HTMLAttributes, ReactElement } from 'react';
+import { ReactElement, HTMLAttributes } from 'react';
+
+/** Stable FNV-1a color bucket for a shell slot name. */
+declare function hashSlotHue(name: string): number;
+/** Whether a composable `debug` query contains the exact `slots` token. */
+declare function isSlotDebugEnabled(search?: string): boolean;
+/** Dev-time visualization derived only from live `data-fx-slot` markers. */
+declare function SlotDebugOverlay(): ReactElement;
 
 type ShellSlotElement = 'aside' | 'div' | 'main' | 'section';
 interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
@@ -8,4 +15,4 @@ interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
 /** Structural shell marker that preserves the caller's semantic element. */
 declare function ShellSlot({ as, name, ...props }: ShellSlotProps): ReactElement;
 
-export { ShellSlot, type ShellSlotElement, type ShellSlotProps };
+export { ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, hashSlotHue, isSlotDebugEnabled };

package/dist/react.js

@@ -1,5 +1,168 @@
 // src/react.tsx
 import { createElement } from "react";
+
+// src/slot-debug.tsx
+import { useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var OVERLAY_Z = 2147483e3;
+var LABEL_CORNERS = [
+  { top: 2, left: 2 },
+  { top: 2, right: 2 },
+  { bottom: 2, left: 2 },
+  { bottom: 2, right: 2 }
+];
+function hashSlotHue(name) {
+  let hash = 2166136261;
+  for (let index = 0; index < name.length; index += 1) {
+    hash ^= name.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) % 360;
+}
+function isSlotDebugEnabled(search = typeof window !== "undefined" ? window.location.search : "") {
+  try {
+    const debug = new URLSearchParams(search).get("debug");
+    return debug?.split(",").some((flag) => flag.trim() === "slots") ?? false;
+  } catch {
+    return false;
+  }
+}
+function measureSlots() {
+  const elements = Array.from(document.querySelectorAll("[data-fx-slot]"));
+  const boxes = [];
+  for (const element of elements) {
+    const name = element.getAttribute("data-fx-slot") ?? "";
+    if (!name) continue;
+    let rect;
+    if (element.firstChild) {
+      const range = document.createRange();
+      range.selectNodeContents(element);
+      rect = range.getBoundingClientRect();
+    } else {
+      rect = element.getBoundingClientRect();
+    }
+    if (rect.width === 0 && rect.height === 0) continue;
+    let depth = 0;
+    let parentName = null;
+    let cursor = element.parentElement;
+    while (cursor) {
+      if (cursor.hasAttribute("data-fx-slot")) {
+        parentName ??= cursor.getAttribute("data-fx-slot");
+        depth += 1;
+      }
+      cursor = cursor.parentElement;
+    }
+    boxes.push({
+      name,
+      parentName,
+      depth,
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height
+    });
+  }
+  return boxes;
+}
+function SlotDebugOverlay() {
+  const [boxes, setBoxes] = useState([]);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    let frame = 0;
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => setBoxes(measureSlots()));
+    };
+    setBoxes(measureSlots());
+    const resizeObserver = new ResizeObserver(schedule);
+    const attach = () => {
+      resizeObserver.disconnect();
+      document.querySelectorAll("[data-fx-slot]").forEach((element) => resizeObserver.observe(element));
+    };
+    attach();
+    const mutationObserver = new MutationObserver((records) => {
+      let markerSetChanged = false;
+      for (const record of records) {
+        if (record.type === "attributes" && record.attributeName === "data-fx-slot") {
+          markerSetChanged = true;
+          break;
+        }
+        if (record.type !== "childList") continue;
+        const nodes = [...record.addedNodes, ...record.removedNodes];
+        markerSetChanged = nodes.some((node) => node instanceof Element && (node.matches("[data-fx-slot]") || node.querySelector("[data-fx-slot]")));
+        if (markerSetChanged) break;
+      }
+      if (markerSetChanged) attach();
+      schedule();
+    });
+    mutationObserver.observe(document.body, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ["data-fx-slot"]
+    });
+    window.addEventListener("resize", schedule);
+    window.addEventListener("scroll", schedule, true);
+    return () => {
+      cancelAnimationFrame(frame);
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+      window.removeEventListener("resize", schedule);
+      window.removeEventListener("scroll", schedule, true);
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      style: {
+        position: "fixed",
+        inset: 0,
+        pointerEvents: "none",
+        zIndex: OVERLAY_Z
+      },
+      "data-fx-slot-overlay": "",
+      children: boxes.map((box, index) => {
+        const hue = hashSlotHue(box.name);
+        const corner = LABEL_CORNERS[box.depth % LABEL_CORNERS.length];
+        const label = box.parentName ? `${box.parentName} \u2192 ${box.name}` : box.name;
+        return /* @__PURE__ */ jsx(
+          "div",
+          {
+            style: {
+              position: "fixed",
+              left: box.left,
+              top: box.top,
+              width: box.width,
+              height: box.height,
+              background: `hsla(${hue}, 65%, 55%, ${Math.min(0.35, 0.1 + box.depth * 0.06)})`,
+              outline: `${Math.max(1, 3 - box.depth)}px solid hsla(${hue}, 65%, 55%, 0.7)`,
+              pointerEvents: "none"
+            },
+            children: /* @__PURE__ */ jsx(
+              "span",
+              {
+                style: {
+                  position: "absolute",
+                  ...corner,
+                  background: `hsla(${hue}, 65%, 25%, 0.9)`,
+                  color: "#fff",
+                  font: "10px/14px ui-monospace, monospace",
+                  padding: "1px 4px",
+                  borderRadius: 2,
+                  whiteSpace: "nowrap"
+                },
+                children: label
+              }
+            )
+          },
+          `${box.name}:${index}`
+        );
+      })
+    }
+  );
+}
+
+// src/react.tsx
 function ShellSlot({
   as = "div",
   name,
@@ -8,5 +171,8 @@ function ShellSlot({
   return createElement(as, { ...props, "data-fx-slot": name });
 }
 export {
-  ShellSlot
+  ShellSlot,
+  SlotDebugOverlay,
+  hashSlotHue,
+  isSlotDebugEnabled
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,6 +36,7 @@
     "react": "^19.0.0"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "bun-types": "^1.3.14",