synabun 1.3.0

package/neural-interface/public/shared/i18n.js

@@ -0,0 +1,147 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Internationalization
+// Lightweight runtime i18n: loads JSON translations at boot,
+// exposes t() / tp() for all modules.
+// ═══════════════════════════════════════════
+
+import { storage } from './storage.js';
+
+let _messages = {};
+let _locale = 'en';
+let _ready = false;
+
+// ── Supported locales (grows as translations are added) ──
+export const SUPPORTED_LOCALES = ['en'];
+
+// ── Locale metadata (for language switcher UI) ──
+export const LOCALE_NAMES = {
+  en: 'English',
+};
+
+// ═══════════════════════════════════════════
+// CORE API
+// ═══════════════════════════════════════════
+
+/**
+ * Resolve a dot-separated key path against a nested object.
+ * t('settings.server.status') → messages.settings.server.status
+ */
+function resolve(obj, path) {
+  return path.split('.').reduce((o, k) => o?.[k], obj);
+}
+
+/**
+ * Translate a key, with optional parameter interpolation.
+ *
+ * @param {string} key  Dot-separated key path (e.g. 'nav.view')
+ * @param {Object} [params]  Interpolation values: "Hello {name}" + { name: 'Dan' }
+ * @returns {string} Translated string, or the key itself if missing
+ *
+ * @example
+ *   t('common.save')                          // "Save"
+ *   t('explorer.importanceTooltip', { n: 8 }) // "Importance: 8/10"
+ */
+export function t(key, params) {
+  let val = resolve(_messages, key);
+  if (val === undefined) {
+    if (_ready) console.warn(`[i18n] Missing key: ${key}`);
+    return key;
+  }
+  if (params && typeof val === 'string') {
+    val = val.replace(/\{(\w+)\}/g, (_, k) => (params[k] != null ? params[k] : `{${k}}`));
+  }
+  return val;
+}
+
+/**
+ * Pluralization helper. Resolves to key.one or key.other based on count.
+ *
+ * @param {string} key   Base key path (e.g. 'search.resultCount')
+ * @param {number} count The number to pluralize on
+ * @param {Object} [params] Extra interpolation values (count is auto-included)
+ * @returns {string}
+ *
+ * @example
+ *   // en.json: { "search": { "resultCount": { "one": "1 result", "other": "{count} results" } } }
+ *   tp('search.resultCount', 1)   // "1 result"
+ *   tp('search.resultCount', 42)  // "42 results"
+ */
+export function tp(key, count, params) {
+  const plural = count === 1 ? 'one' : 'other';
+  return t(`${key}.${plural}`, { count, ...params });
+}
+
+/**
+ * Get the current locale code (e.g. 'en', 'es').
+ * Use this for Intl APIs: date.toLocaleDateString(getLocale(), ...)
+ */
+export function getLocale() {
+  return _locale;
+}
+
+/**
+ * Check if translations have been loaded.
+ */
+export function isReady() {
+  return _ready;
+}
+
+// ═══════════════════════════════════════════
+// INITIALIZATION
+// ═══════════════════════════════════════════
+
+/**
+ * Detect the user's preferred locale.
+ * Priority: localStorage explicit choice → browser language → 'en'
+ */
+function detectLocale() {
+  // 1. Explicit user preference
+  const saved = storage.getItem('synabun-locale');
+  if (saved && SUPPORTED_LOCALES.includes(saved)) return saved;
+  // 2. Browser language
+  const browser = (navigator.language || 'en').slice(0, 2).toLowerCase();
+  if (SUPPORTED_LOCALES.includes(browser)) return browser;
+  // 3. Default
+  return 'en';
+}
+
+/**
+ * Load translations. Call this ONCE at app boot, BEFORE any UI modules init.
+ * Typically the first thing in the entry point's top-level await.
+ *
+ * @param {string} [locale] Force a specific locale (skips detection)
+ */
+export async function initI18n(locale) {
+  _locale = locale || detectLocale();
+  try {
+    const resp = await fetch(`/i18n/${_locale}.json`);
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    _messages = await resp.json();
+  } catch (err) {
+    // Fallback to English if the requested locale file fails
+    if (_locale !== 'en') {
+      console.warn(`[i18n] Failed to load '${_locale}', falling back to 'en'`);
+      _locale = 'en';
+      try {
+        const resp = await fetch('/i18n/en.json');
+        if (resp.ok) _messages = await resp.json();
+      } catch {
+        console.error('[i18n] Failed to load English fallback');
+      }
+    } else {
+      console.error('[i18n] Failed to load English translations:', err);
+    }
+  }
+  _ready = true;
+  document.documentElement.lang = _locale;
+}
+
+/**
+ * Switch to a different locale. Persists to localStorage and reloads.
+ * @param {string} locale
+ */
+export function setLocale(locale) {
+  if (!SUPPORTED_LOCALES.includes(locale)) return;
+  storage.setItem('synabun-locale', locale);
+  window.location.reload();
+}

package/neural-interface/public/shared/registry.js

@@ -0,0 +1,82 @@
+// ═══════════════════════════════════════════
+// REGISTRY — feature registry for variant capabilities
+// ═══════════════════════════════════════════
+//
+// Each variant (3D / 2D) registers its identity, capabilities, and UI
+// extensions on boot. Shared UI reads the registry to decide what to render.
+
+const _registry = {
+  variant: null,            // '3d' | '2d' | future variants
+  capabilities: new Set(),  // e.g. 'camera-hud', 'minimap', 'hulls', 'lasso', 'controls-panel'
+  navbarButtons: [],        // { zone, order, html, init }  (legacy, kept for compat)
+  menuItems: [],            // { menu, order, type, id, label, shortcut?, init }
+  helpSections: [],         // { order, html }
+  settingsTabs: [],         // { id, label, icon, builder, afterRender }
+  keyboardShortcuts: [],    // { key, description, handler }
+};
+
+// ── Registration API ──
+
+/**
+ * Register the active variant and its capabilities.
+ * Called once at variant boot time.
+ * @param {{ variant: string, capabilities?: string[] }} config
+ */
+export function registerVariant(config) {
+  _registry.variant = config.variant;
+  _registry.capabilities = new Set(config.capabilities || []);
+}
+
+/**
+ * Register an extra button for the top navbar.
+ * @param {{ zone: string, order: number, html: string, init: Function }} spec
+ */
+export function registerNavbarButton(spec) {
+  _registry.navbarButtons.push(spec);
+  _registry.navbarButtons.sort((a, b) => a.order - b.order);
+}
+
+/**
+ * Register a menu item for the OS-style menubar.
+ * @param {{ menu: string, order: number, type: string, id: string, label: string, shortcut?: string, init?: Function }} spec
+ */
+export function registerMenuItem(spec) {
+  _registry.menuItems.push(spec);
+  _registry.menuItems.sort((a, b) => a.order - b.order);
+}
+
+/**
+ * Register an extra section for the help modal.
+ * @param {{ order: number, html: string }} spec
+ */
+export function registerHelpSection(spec) {
+  _registry.helpSections.push(spec);
+  _registry.helpSections.sort((a, b) => a.order - b.order);
+}
+
+/**
+ * Register an extra tab for the settings panel.
+ * @param {{ id: string, label: string, icon: string, builder: Function, afterRender?: Function }} spec
+ */
+export function registerSettingsTab(spec) {
+  _registry.settingsTabs.push(spec);
+}
+
+/**
+ * Register a keyboard shortcut (for help display and central handler).
+ * @param {{ key: string, description: string, handler: Function }} spec
+ */
+export function registerKeyboardShortcut(spec) {
+  _registry.keyboardShortcuts.push(spec);
+}
+
+// ── Query API ──
+
+export function getVariant() { return _registry.variant; }
+export function hasCapability(name) { return _registry.capabilities.has(name); }
+export function getNavbarButtons() { return _registry.navbarButtons; }
+export function getMenuItems() { return _registry.menuItems; }
+export function getHelpSections() { return _registry.helpSections; }
+export function getSettingsTabs() { return _registry.settingsTabs; }
+export function getKeyboardShortcuts() { return _registry.keyboardShortcuts; }
+export function getRegistry() { return _registry; }

package/neural-interface/public/shared/state.js

@@ -0,0 +1,86 @@
+// ═══════════════════════════════════════════
+// STATE — shared reactive state store + event bus
+// ═══════════════════════════════════════════
+//
+// All UI components read/write this object.
+// Variants (3D / 2D) listen for changes via the event bus.
+// Variant-specific state (graph, bloom, frustum, etc.) stays in the variant.
+
+export const state = {
+  // ── Data (loaded from API) ──
+  allNodes: [],
+  allLinks: [],
+  categoryMetadata: {},    // { name: { description, color, parent, is_parent, logo } }
+  allCategoryNames: [],    // ordered list of category names from server
+  categoryDescriptions: {},// { name: description }
+
+  // ── Selection ──
+  selectedNodeId: null,
+  hoveredNodeId: null,
+  focusedNodeId: null,
+
+  // ── Search ──
+  searchResults: null,     // null = no active search, Set of IDs = active search
+  searchQuery: '',
+
+  // ── Category visibility ──
+  activeCategories: new Set(),
+
+  // ── Multi-select ──
+  multiSelected: new Set(),
+
+  // ── UI toggles ──
+  labelsVisible: true,
+  labelSizeMultiplier: 1.0,
+
+  // ── Link mode ──
+  linkMode: 'off',         // 'off' | 'intra' | 'all'
+  linkTypeFilter: 'all',
+
+  // ── Grid snap ──
+  gridSnap: false,
+  gridSize: 20,
+
+  // ── Terminal links ──
+  linkedSessionIds: new Set(),  // session IDs currently in an active link
+};
+
+
+// ═══════════════════════════════════════════
+// EVENT BUS — lightweight pub/sub
+// ═══════════════════════════════════════════
+
+const _listeners = {};
+
+/**
+ * Emit an event to all registered listeners.
+ * @param {string} event   Event name (e.g. 'selection-changed', 'data-loaded')
+ * @param {*}      [data]  Payload passed to each listener
+ */
+export function emit(event, data) {
+  const fns = _listeners[event];
+  if (fns) fns.forEach(fn => fn(data));
+}
+
+/**
+ * Subscribe to an event. Returns an unsubscribe function.
+ * @param {string}   event  Event name
+ * @param {Function} fn     Listener
+ * @returns {Function} Unsubscribe function
+ */
+export function on(event, fn) {
+  if (!_listeners[event]) _listeners[event] = [];
+  _listeners[event].push(fn);
+  return () => { _listeners[event] = _listeners[event].filter(f => f !== fn); };
+}
+
+/**
+ * Remove a specific listener for an event.
+ * @param {string}   event  Event name
+ * @param {Function} fn     Listener to remove
+ */
+export function off(event, fn) {
+  if (_listeners[event]) {
+    _listeners[event] = _listeners[event].filter(f => f !== fn);
+  }
+}

package/neural-interface/public/shared/storage.js

@@ -0,0 +1,150 @@
+// ═══════════════════════════════════════════
+// STORAGE — Server-synced persistent state
+// ═══════════════════════════════════════════
+//
+// Drop-in replacement for localStorage calls.
+// Data persists to data/ui-state.json on the server.
+//
+// Self-hydrating: the module-level `await` ensures any module that
+// imports from storage.js gets a populated cache before its own
+// body executes. This is critical for modules like gfx.js that call
+// loadGfxConfig() at import time.
+//
+// The in-memory cache ensures synchronous reads (zero latency).
+// Writes are async but invisible to callers.
+
+const _cache = {};
+let _dirty = {};
+let _flushTimer = null;
+let _hydrated = false;
+const DEBOUNCE_MS = 500;
+
+// ── Hydrate from server ──────────────────────────────
+
+async function _hydrate() {
+  let serverData = null;
+  try {
+    const res = await fetch('/api/ui-state');
+    if (res.ok) serverData = await res.json();
+  } catch { /* server unreachable */ }
+
+  if (serverData && Object.keys(serverData).filter(k => !k.startsWith('_')).length > 0) {
+    // Normal boot: hydrate from server file
+    for (const [key, value] of Object.entries(serverData)) {
+      if (key.startsWith('_')) continue;
+      _cache[key] = typeof value === 'string' ? value : JSON.stringify(value);
+    }
+  } else {
+    // First run or server down: import from localStorage
+    console.info('[storage] Migrating localStorage to server...');
+    _migrateFromLocalStorage();
+    // Build dirty set from everything we imported
+    for (const [key, val] of Object.entries(_cache)) {
+      try { _dirty[key] = JSON.parse(val); } catch { _dirty[key] = val; }
+    }
+    if (Object.keys(_dirty).length > 0) {
+      await _flushToServer();
+      console.info('[storage] Migration complete. Data saved to data/ui-state.json');
+    }
+  }
+  _hydrated = true;
+}
+
+// Self-hydrate at module load — blocks dependents until cache is ready
+await _hydrate();
+
+// ── Drop-in API (mirrors localStorage) ───────────────
+
+export const storage = {
+  getItem(key) {
+    return _cache[key] ?? null;
+  },
+
+  setItem(key, value) {
+    const strValue = String(value);
+    if (_cache[key] === strValue) return; // no-op if unchanged
+    _cache[key] = strValue;
+    // Parse back to native type for the server (avoids double-encoding JSON)
+    try { _dirty[key] = JSON.parse(strValue); } catch { _dirty[key] = strValue; }
+    _scheduleDebouncedFlush();
+  },
+
+  removeItem(key) {
+    if (!(key in _cache)) return;
+    delete _cache[key];
+    _dirty[key] = null; // null signals deletion to the server
+    _scheduleDebouncedFlush();
+  },
+};
+
+// ── Debounced flush to server ────────────────────────
+
+function _scheduleDebouncedFlush() {
+  if (_flushTimer) clearTimeout(_flushTimer);
+  _flushTimer = setTimeout(_flushToServer, DEBOUNCE_MS);
+}
+
+async function _flushToServer() {
+  const payload = { ..._dirty };
+  _dirty = {};
+  _flushTimer = null;
+  if (Object.keys(payload).length === 0) return;
+  try {
+    const res = await fetch('/api/ui-state', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  } catch (err) {
+    console.warn('[storage] Flush failed:', err.message, '— will retry');
+    // Re-queue failed keys (don't overwrite newer dirty values)
+    for (const [k, v] of Object.entries(payload)) {
+      if (!(k in _dirty)) _dirty[k] = v;
+    }
+    _scheduleDebouncedFlush();
+  }
+}
+
+// ── Flush on page unload (sendBeacon for reliability) ──
+
+window.addEventListener('beforeunload', () => {
+  if (_flushTimer) {
+    clearTimeout(_flushTimer);
+    _flushTimer = null;
+  }
+  // Merge any pending dirty keys
+  const payload = { ..._dirty };
+  _dirty = {};
+  if (Object.keys(payload).length === 0) return;
+  navigator.sendBeacon(
+    '/api/ui-state',
+    new Blob([JSON.stringify(payload)], { type: 'application/json' })
+  );
+});
+
+// ── Migration helper ─────────────────────────────────
+
+function _migrateFromLocalStorage() {
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (key && (key.startsWith('neural-') || key.startsWith('synabun-'))) {
+      _cache[key] = localStorage.getItem(key);
+    }
+  }
+}
+
+// ── Utilities ────────────────────────────────────────
+
+/** Force an immediate flush (useful for testing or explicit save actions) */
+export async function flushStorage() {
+  if (_flushTimer) {
+    clearTimeout(_flushTimer);
+    _flushTimer = null;
+  }
+  await _flushToServer();
+}
+
+export function isHydrated() {
+  return _hydrated;
+}