big restructure

web/js/core/app-dom.js

@@ -0,0 +1,27 @@
+const warned = new Set();
+
+export const warnOnce = (code, message, details = {}) => {
+  const key = `${code}:${message}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[${code}] ${message}`, details);
+};
+
+export const requireEl = (selector, details = {}) => {
+  const el = document.querySelector(selector);
+  if (!el) {
+    warnOnce('UI_EL_MISSING', `Missing element: ${selector}`, details);
+    return null;
+  }
+  return el;
+};
+
+export const requireAll = (selector, details = {}) => {
+  const list = Array.from(document.querySelectorAll(selector));
+  if (!list.length) {
+    warnOnce('UI_EL_MISSING', `Missing elements: ${selector}`, details);
+  }
+  return list;
+};
+
+export const optionalEl = (selector) => document.querySelector(selector);

web/js/core/app-grid-factory.js

@@ -1,3 +1,5 @@
+import { warnOnce } from './app-dom.js';
+
 export function createServerGrid(options) {
   const {
     container,
@@ -22,6 +24,12 @@ export function createServerGrid(options) {
   const gridjsLib = gridjs || window.gridjs;
   const containerEl = typeof container === 'string' ? document.querySelector(container) : container;
   if (!containerEl || !gridjsLib) {
+    if (!containerEl) {
+      warnOnce('UI_EL_MISSING', `Missing grid container: ${container}`, { module: 'grid-factory' });
+    }
+    if (!gridjsLib) {
+      warnOnce('UI_LIB_MISSING', 'Grid.js not available', { module: 'grid-factory' });
+    }
     return null;
   }