this.gui 1.1.23 → 1.1.25

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "this.gui",
   "private": false,
-  "version": "1.1.23",
+  "version": "1.1.25",
   "type": "module",
   "main": "dist/this-gui.umd.js",
   "module": "dist/this-gui.es.js",
@@ -17,7 +17,7 @@
     "gui": "./dist/bin/cli.js"
   },
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && node -e \"import('./vite.config.js').then(m => m.buildFinished())\"",
     "lint": "eslint .",
     "dev": "vite",
     "dev:lib": "vite build --watch",

package/dist/notes/Proyect.md

@@ -1,109 +0,0 @@
-Ocultar/mostrar barras, dar pantalla completa al lienzo, y encima montar un sistema de colocación (2D/3D) que se hidrate desde JSON.
-
-Aquí te dejo un plan claro (sin código) para que lo aterricemos paso a paso:
-
-1) API del Shell (layout declarativo)
-
-Define un spec de layout que controle visibilidad, posición y estilo de las barras (y que sea mutable en runtime):
-
-{
-  "layout": {
-    "navbar": { "visible": true,  "position": "fixed" },
-    "leftDrawer": { "visible": true,  "width": 260 },
-    "rightDrawer": { "visible": false, "width": 280 },
-    "stickyOptions": { "visible": false },
-    "footer": { "visible": true },
-    "canvas": {
-      "mode": "2d",         // "2d" | "3d"
-      "fullscreen": false,  // si true, el shell oculta barras y expande el lienzo
-      "bg": "transparent"
-    }
-  }
-}
-
-	•	El shell aplica el spec y actualiza insets (como ya haces) cuando algo es permanente.
-	•	Si canvas.fullscreen = true, el shell oculta NavBar/Drawers/Sticky/Footer y setea insets a 0 → el “campo” queda a pantalla completa.
-
-2) Motor de colocación (2D primero, 3D después)
-
-Para el colocador 2D, usa una cuadrícula declarativa. Piensa en áreas CSS Grid con responsive:
-
-{
-  "canvas2D": {
-    "grid": {
-      "template": {
-        "xs": { "cols": "1fr", "rows": "auto 1fr auto", "areas": ["header","content","hud"] },
-        "md": { "cols": "240px 1fr", "rows": "auto 1fr", "areas": ["sidebar header","sidebar content"] }
-      },
-      "gap": 8
-    },
-    "items": [
-      { "id": "header",  "component": { "type": "Text", "props": { "variant": "h4", "children": "Scene" } } },
-      { "id": "sidebar", "component": { "type": "Panel", "props": { "title": "Layers" } } },
-      { "id": "content", "component": { "type": "Viewport2D", "props": { "controls": true } } },
-      { "id": "hud",     "component": { "type": "StickyOptionsTop", "props": { "items": [/* … */] } } }
-    ]
-  }
-}
-
-	•	template define áreas por breakpoint (xs/md/etc.).
-	•	items asigna qué se renderiza en cada área (resuelto por tu registry + resolvers).
-	•	Esto te da un “layout engine” 2D declarativo, perfecto para AR-lite (HUDs, overlays).
-
-Para 3D, la misma idea, pero con un Viewport3D (three.js/Babylon) como componente. El grid sigue sirviendo para HUDs y paneles laterales mientras el lienzo 3D ocupa el área content.
-
-3) Controles de visibilidad y modos (runtime)
-
-Agrega un canal simple de acciones declarativas para mutar el spec:
-
-{
-  "actions": [
-    { "id": "toggleFull", "type": "toggle", "path": "layout.canvas.fullscreen" },
-    { "id": "showRight",  "type": "set",    "path": "layout.rightDrawer.visible", "value": true }
-  ],
-  "bindings": [
-    { "event": "kbd:F", "action": "toggleFull" },
-    { "event": "ui:openContext", "action": "showRight" }
-  ]
-}
-
-	•	El shell expone un dispatcher que entiende toggle/set sobre rutas JSON (path).
-	•	Permite atajos (teclado), botones de UI, o señales externas (servidor/IA).
-
-4) Resolver genérico + resolvers por componente
-	•	Mantén los resolvers por componente (Button, Link, NavBar, Viewport2D/3D, etc.) para mapear JSON → props reales.
-	•	El resolver genérico (inyector) toma el árbol JSON y delega por type al resolver adecuado (registrado en tu GuiRegistry).
-	•	Así puedes hidratar todo el shell (barras + canvas + grid + items) desde un único spec.
-
-5) Slots y Portal (overlay HUD)
-	•	Define “slots” especiales (ej. overlay, hud, notifications) que rendericen vía portal encima del canvas.
-	•	Tus StickyOptionsTop u otras capas pueden vivir ahí sin afectar insets del shell.
-
-6) Persistencia + Replay
-	•	Guarda el spec actual (y su historial) en localStorage o en backend para reproducir estados y compartir escenas/pantallas.
-	•	Útil para AR colaborativo y “deep links” a UIs derivadas por IA.
-
-7) Rendimiento
-	•	Evita re-render global del shell: cuando mutas visibilidad o áreas, memoriza subárboles.
-	•	Para 3D, desacopla el ciclo de render del estado de React cuando sea necesario.
-
-8) Roadmap chiquito (prioridades)
-	1.	Spec de layout con visibilidad + fullscreen (ya puedes hacerlo con tu shell actual).
-	2.	Grid 2D declarativo con áreas responsive (pequeño motor CSS Grid).
-	3.	Slots/Portal para HUD/Overlay.
-	4.	Registry + resolvers para los componentes que entren al grid (ya lo estás haciendo).
-	5.	Acciones declarativas (toggle/set) + bindings básicos.
-	6.	Viewport3D como primitivo (después).
-
-⸻
-
-Con esto:
-	•	Puedes ocultar/mostrar barras a voluntad o entrar en fullscreen.
-	•	Tienes un lienzo central controlado por spec.
-	•	Puedes colocar elementos 2D (y luego 3D) de forma declarativa y responsive.
-	•	Todo eso conversando con tu registry y los resolvers que ya estás construyendo.
-
-Cuando quieras, te redacto un spec mínimo de ejemplo (end-to-end) que tu shell pueda consumir hoy mismo para:
-	1.	navbar visible, leftDrawer visible, rightDrawer oculto;
-	2.	grid 2D con sidebar/header/content;
-	3.	botón que activa fullscreen.

package/dist/overall approach.md

@@ -1,93 +0,0 @@
-compact technical brief of the overall approach (props vs config vs viewported configs), with structure, versatility, declarativity, and scope.
-
-1) Plain React props (current/“classic”)
-
-Structure: <Footer title="…" links={[…]} socialLinks={[…]} />
-Pros
-	•	Familiar React ergonomics.
-	•	Strong TypeScript IntelliSense on each prop.
-	•	Easy to tree-shake and to reason about in component code.
-
-Cons
-	•	Gets verbose as components grow.
-	•	Hard to switch “modes” (desktop/mobile/minimal/full) without duplicating prop sets.
-	•	Not naturally serializable (harder to hydrate from pure JSON or an external CMS).
-
-Use when
-	•	App code writes JSX directly.
-	•	Variations are small and local.
-
-2) Single config object
-
-Structure: <Footer config={{ title:"…", links:[…], socialLinks:[…] }} />
-Pros
-	•	Declarative & serializable: perfect for JSON-driven UIs, CMS/Llama/Lego-style composition.
-	•	One entrypoint for “shape evolution”: adding/removing options doesn’t churn the JSX signature.
-	•	Easier to diff/patch at runtime (hot updates, remote editing, A/B tests).
-
-Cons
-	•	Slightly less IDE precision unless you type config well (e.g., FooterConfig).
-	•	If you mix both props and config, you need clear precedence rules.
-
-Use when
-	•	You want to drive UI from data (JSON), live-edit, or swap configurations on the fly.
-	•	You’re aiming at a “player” model later (render UIs from configs).
-
-Recommended pattern
-	•	Support both: keep top-level props for ergonomics, plus an optional config. Component merges: final = { ...defaults, ...config, ...propsOverrides }.
-
-3) Viewport-aware configs (declarative responsiveness)
-
-Structure A (per-prop):
-size="pill" or size={{ xs: "icons", md: "pill" }}
-
-Structure B (whole-config overrides):
-
-<StickyOptionsTop
-  config={{ items: desktopItems }}
-  viewport={{
-    xs: { config: { items: mobileItems } },
-    sm: { config: { items: mobileItems } }
-  }}
-/>
-
-(Resolved by your viewport.ts: resolveViewportProp / resolveResponsiveConfig.)
-
-Pros
-	•	Responsiveness is data, not scattered useMediaQuery logic.
-	•	Plays great with JSON: one base config + sparse overrides per breakpoint.
-	•	Testable & SSR-friendly (you can inject a width override).
-
-Cons
-	•	Slightly more indirection; you need a tiny resolver layer (which you now have).
-	•	Authors must learn the pattern (base + per-breakpoint overrides).
-
-Use when
-	•	The same component must present different variants by viewport.
-	•	You want a single source of truth for mobile/desktop/XL differences.
-
-Putting it together (recommended architecture)
-	•	Component API supports both:
-	•	Classic props (ergonomic for app devs).
-	•	config (for JSON-driven/declarative scenarios).
-	•	Optional viewport to override either specific props or the whole config per breakpoint.
-	•	Resolver layer (inside each component):
-	1.	Gather defaults.
-	2.	Merge config.
-	3.	Apply classic prop overrides (if both exist, props win).
-	4.	Apply viewport overrides using your resolveViewportProp/resolveResponsiveConfig.
-	5.	Render.
-
-This yields:
-	•	Versatility: JSX convenience and data-driven control.
-	•	Declarativity: All variants can be expressed as JSON and swapped live.
-	•	Scope/Future-proofing: Same pattern works for a headless “GUI Player,” CMS, LLM emitters, or Web Components later (just feed the same config/viewport JSON).
-	•	Low coupling: Components don’t import useMediaQuery everywhere; the viewport resolver centralizes responsive decisions.
-
-Migration strategy (quick)
-	1.	Keep your existing props as-is.
-	2.	Add optional config and viewport to priority-merge.
-	3.	Start using viewport.ts in 1–2 components (e.g., StickyOptionsTop, Footer) to prove the flow.
-	4.	Document the precedence rule: defaults < config < props < viewport overrides.
-
-This gives you the best of all worlds: ergonomic props for developers, clean JSON for declarative UIs, and a compact, testable way to express responsive variants without scattering logic.

package/public/notes/Proyect.md

@@ -1,109 +0,0 @@
-Ocultar/mostrar barras, dar pantalla completa al lienzo, y encima montar un sistema de colocación (2D/3D) que se hidrate desde JSON.
-
-Aquí te dejo un plan claro (sin código) para que lo aterricemos paso a paso:
-
-1) API del Shell (layout declarativo)
-
-Define un spec de layout que controle visibilidad, posición y estilo de las barras (y que sea mutable en runtime):
-
-{
-  "layout": {
-    "navbar": { "visible": true,  "position": "fixed" },
-    "leftDrawer": { "visible": true,  "width": 260 },
-    "rightDrawer": { "visible": false, "width": 280 },
-    "stickyOptions": { "visible": false },
-    "footer": { "visible": true },
-    "canvas": {
-      "mode": "2d",         // "2d" | "3d"
-      "fullscreen": false,  // si true, el shell oculta barras y expande el lienzo
-      "bg": "transparent"
-    }
-  }
-}
-
-	•	El shell aplica el spec y actualiza insets (como ya haces) cuando algo es permanente.
-	•	Si canvas.fullscreen = true, el shell oculta NavBar/Drawers/Sticky/Footer y setea insets a 0 → el “campo” queda a pantalla completa.
-
-2) Motor de colocación (2D primero, 3D después)
-
-Para el colocador 2D, usa una cuadrícula declarativa. Piensa en áreas CSS Grid con responsive:
-
-{
-  "canvas2D": {
-    "grid": {
-      "template": {
-        "xs": { "cols": "1fr", "rows": "auto 1fr auto", "areas": ["header","content","hud"] },
-        "md": { "cols": "240px 1fr", "rows": "auto 1fr", "areas": ["sidebar header","sidebar content"] }
-      },
-      "gap": 8
-    },
-    "items": [
-      { "id": "header",  "component": { "type": "Text", "props": { "variant": "h4", "children": "Scene" } } },
-      { "id": "sidebar", "component": { "type": "Panel", "props": { "title": "Layers" } } },
-      { "id": "content", "component": { "type": "Viewport2D", "props": { "controls": true } } },
-      { "id": "hud",     "component": { "type": "StickyOptionsTop", "props": { "items": [/* … */] } } }
-    ]
-  }
-}
-
-	•	template define áreas por breakpoint (xs/md/etc.).
-	•	items asigna qué se renderiza en cada área (resuelto por tu registry + resolvers).
-	•	Esto te da un “layout engine” 2D declarativo, perfecto para AR-lite (HUDs, overlays).
-
-Para 3D, la misma idea, pero con un Viewport3D (three.js/Babylon) como componente. El grid sigue sirviendo para HUDs y paneles laterales mientras el lienzo 3D ocupa el área content.
-
-3) Controles de visibilidad y modos (runtime)
-
-Agrega un canal simple de acciones declarativas para mutar el spec:
-
-{
-  "actions": [
-    { "id": "toggleFull", "type": "toggle", "path": "layout.canvas.fullscreen" },
-    { "id": "showRight",  "type": "set",    "path": "layout.rightDrawer.visible", "value": true }
-  ],
-  "bindings": [
-    { "event": "kbd:F", "action": "toggleFull" },
-    { "event": "ui:openContext", "action": "showRight" }
-  ]
-}
-
-	•	El shell expone un dispatcher que entiende toggle/set sobre rutas JSON (path).
-	•	Permite atajos (teclado), botones de UI, o señales externas (servidor/IA).
-
-4) Resolver genérico + resolvers por componente
-	•	Mantén los resolvers por componente (Button, Link, NavBar, Viewport2D/3D, etc.) para mapear JSON → props reales.
-	•	El resolver genérico (inyector) toma el árbol JSON y delega por type al resolver adecuado (registrado en tu GuiRegistry).
-	•	Así puedes hidratar todo el shell (barras + canvas + grid + items) desde un único spec.
-
-5) Slots y Portal (overlay HUD)
-	•	Define “slots” especiales (ej. overlay, hud, notifications) que rendericen vía portal encima del canvas.
-	•	Tus StickyOptionsTop u otras capas pueden vivir ahí sin afectar insets del shell.
-
-6) Persistencia + Replay
-	•	Guarda el spec actual (y su historial) en localStorage o en backend para reproducir estados y compartir escenas/pantallas.
-	•	Útil para AR colaborativo y “deep links” a UIs derivadas por IA.
-
-7) Rendimiento
-	•	Evita re-render global del shell: cuando mutas visibilidad o áreas, memoriza subárboles.
-	•	Para 3D, desacopla el ciclo de render del estado de React cuando sea necesario.
-
-8) Roadmap chiquito (prioridades)
-	1.	Spec de layout con visibilidad + fullscreen (ya puedes hacerlo con tu shell actual).
-	2.	Grid 2D declarativo con áreas responsive (pequeño motor CSS Grid).
-	3.	Slots/Portal para HUD/Overlay.
-	4.	Registry + resolvers para los componentes que entren al grid (ya lo estás haciendo).
-	5.	Acciones declarativas (toggle/set) + bindings básicos.
-	6.	Viewport3D como primitivo (después).
-
-⸻
-
-Con esto:
-	•	Puedes ocultar/mostrar barras a voluntad o entrar en fullscreen.
-	•	Tienes un lienzo central controlado por spec.
-	•	Puedes colocar elementos 2D (y luego 3D) de forma declarativa y responsive.
-	•	Todo eso conversando con tu registry y los resolvers que ya estás construyendo.
-
-Cuando quieras, te redacto un spec mínimo de ejemplo (end-to-end) que tu shell pueda consumir hoy mismo para:
-	1.	navbar visible, leftDrawer visible, rightDrawer oculto;
-	2.	grid 2D con sidebar/header/content;
-	3.	botón que activa fullscreen.

package/public/overall approach.md

@@ -1,93 +0,0 @@
-compact technical brief of the overall approach (props vs config vs viewported configs), with structure, versatility, declarativity, and scope.
-
-1) Plain React props (current/“classic”)
-
-Structure: <Footer title="…" links={[…]} socialLinks={[…]} />
-Pros
-	•	Familiar React ergonomics.
-	•	Strong TypeScript IntelliSense on each prop.
-	•	Easy to tree-shake and to reason about in component code.
-
-Cons
-	•	Gets verbose as components grow.
-	•	Hard to switch “modes” (desktop/mobile/minimal/full) without duplicating prop sets.
-	•	Not naturally serializable (harder to hydrate from pure JSON or an external CMS).
-
-Use when
-	•	App code writes JSX directly.
-	•	Variations are small and local.
-
-2) Single config object
-
-Structure: <Footer config={{ title:"…", links:[…], socialLinks:[…] }} />
-Pros
-	•	Declarative & serializable: perfect for JSON-driven UIs, CMS/Llama/Lego-style composition.
-	•	One entrypoint for “shape evolution”: adding/removing options doesn’t churn the JSX signature.
-	•	Easier to diff/patch at runtime (hot updates, remote editing, A/B tests).
-
-Cons
-	•	Slightly less IDE precision unless you type config well (e.g., FooterConfig).
-	•	If you mix both props and config, you need clear precedence rules.
-
-Use when
-	•	You want to drive UI from data (JSON), live-edit, or swap configurations on the fly.
-	•	You’re aiming at a “player” model later (render UIs from configs).
-
-Recommended pattern
-	•	Support both: keep top-level props for ergonomics, plus an optional config. Component merges: final = { ...defaults, ...config, ...propsOverrides }.
-
-3) Viewport-aware configs (declarative responsiveness)
-
-Structure A (per-prop):
-size="pill" or size={{ xs: "icons", md: "pill" }}
-
-Structure B (whole-config overrides):
-
-<StickyOptionsTop
-  config={{ items: desktopItems }}
-  viewport={{
-    xs: { config: { items: mobileItems } },
-    sm: { config: { items: mobileItems } }
-  }}
-/>
-
-(Resolved by your viewport.ts: resolveViewportProp / resolveResponsiveConfig.)
-
-Pros
-	•	Responsiveness is data, not scattered useMediaQuery logic.
-	•	Plays great with JSON: one base config + sparse overrides per breakpoint.
-	•	Testable & SSR-friendly (you can inject a width override).
-
-Cons
-	•	Slightly more indirection; you need a tiny resolver layer (which you now have).
-	•	Authors must learn the pattern (base + per-breakpoint overrides).
-
-Use when
-	•	The same component must present different variants by viewport.
-	•	You want a single source of truth for mobile/desktop/XL differences.
-
-Putting it together (recommended architecture)
-	•	Component API supports both:
-	•	Classic props (ergonomic for app devs).
-	•	config (for JSON-driven/declarative scenarios).
-	•	Optional viewport to override either specific props or the whole config per breakpoint.
-	•	Resolver layer (inside each component):
-	1.	Gather defaults.
-	2.	Merge config.
-	3.	Apply classic prop overrides (if both exist, props win).
-	4.	Apply viewport overrides using your resolveViewportProp/resolveResponsiveConfig.
-	5.	Render.
-
-This yields:
-	•	Versatility: JSX convenience and data-driven control.
-	•	Declarativity: All variants can be expressed as JSON and swapped live.
-	•	Scope/Future-proofing: Same pattern works for a headless “GUI Player,” CMS, LLM emitters, or Web Components later (just feed the same config/viewport JSON).
-	•	Low coupling: Components don’t import useMediaQuery everywhere; the viewport resolver centralizes responsive decisions.
-
-Migration strategy (quick)
-	1.	Keep your existing props as-is.
-	2.	Add optional config and viewport to priority-merge.
-	3.	Start using viewport.ts in 1–2 components (e.g., StickyOptionsTop, Footer) to prove the flow.
-	4.	Document the precedence rule: defaults < config < props < viewport overrides.
-
-This gives you the best of all worlds: ergonomic props for developers, clean JSON for declarative UIs, and a compact, testable way to express responsive variants without scattering logic.