aurasu 0.1.0 → 0.1.2

package/src/runtime/ui-settings.js

@@ -0,0 +1,227 @@
+import {
+  listUiContrastChoices,
+  listUiDensityChoices,
+  listUiThemeChoices,
+} from './ui-theme.js';
+
+function hasUiMethod(name) {
+  return Boolean(globalThis.aura?.ui) && typeof globalThis.aura.ui[name] === 'function';
+}
+
+function activeTheme() {
+  return hasUiMethod('getTheme') ? globalThis.aura.ui.getTheme() : null;
+}
+
+function cloneSettingsValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneSettingsValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneSettingsValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+function normalizeOptions(options) {
+  return Array.isArray(options)
+    ? options
+      .filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry))
+      .map((entry) => ({
+        id: typeof entry.id === 'string' ? entry.id.trim() : '',
+        label: typeof entry.label === 'string' && entry.label.trim().length > 0 ? entry.label : String(entry.id || ''),
+        description: typeof entry.description === 'string' ? entry.description : null,
+        disabled: entry.disabled === true,
+      }))
+      .filter((entry) => entry.id.length > 0)
+    : [];
+}
+
+function renderInfoText(id, label = null, description = null) {
+  if (label) {
+    globalThis.aura.ui.text(`${id}-label`, {
+      text: label,
+      size: 12,
+      color: activeTheme()?.mutedTextColor || '#9db2cb',
+    });
+  }
+  if (description) {
+    globalThis.aura.ui.text(`${id}-description`, {
+      text: description,
+      size: 13,
+      color: activeTheme()?.mutedTextColor || '#9db2cb',
+    });
+  }
+}
+
+export function readViewState(nodeId) {
+  if (!hasUiMethod('getViewState')) return null;
+  return globalThis.aura.ui.getViewState(nodeId) || null;
+}
+
+export function wasViewClicked(nodeId) {
+  const state = readViewState(nodeId);
+  return state?.clicked === true || state?.activated === true;
+}
+
+export function readBooleanViewValue(nodeId, fallback = false) {
+  const state = readViewState(nodeId);
+  return typeof state?.value === 'boolean' ? state.value : fallback;
+}
+
+export function readNumberViewValue(nodeId, fallback = 0) {
+  const state = readViewState(nodeId);
+  return Number.isFinite(Number(state?.value)) ? Number(state.value) : fallback;
+}
+
+export function renderSegmentedControl({
+  id,
+  label = null,
+  description = null,
+  value = null,
+  options = [],
+} = {}) {
+  if (!hasUiMethod('beginColumn') || !hasUiMethod('beginRow') || !hasUiMethod('button')) {
+    return {
+      ok: false,
+      reasonCode: 'ui_segmented_runtime_unavailable',
+      value,
+    };
+  }
+
+  const normalizedOptions = normalizeOptions(options);
+  if (typeof id !== 'string' || id.trim().length <= 0 || normalizedOptions.length <= 0) {
+    return {
+      ok: false,
+      reasonCode: 'ui_segmented_invalid_options',
+      value,
+    };
+  }
+
+  const theme = activeTheme();
+  const rootId = id.trim();
+  globalThis.aura.ui.beginColumn({
+    id: `${rootId}-group`,
+    gap: 6,
+    width: 'fill',
+  });
+  renderInfoText(rootId, label, description);
+  globalThis.aura.ui.beginRow({
+    id: `${rootId}-row`,
+    gap: 8,
+    width: 'fill',
+  });
+  for (const option of normalizedOptions) {
+    const active = option.id === value;
+    globalThis.aura.ui.button(`${rootId}-${option.id}`, {
+      label: option.label,
+      width: 'fill',
+      disabled: option.disabled === true,
+      background: active ? (theme?.buttonFocusColor || '#1e5b97') : (theme?.buttonColor || '#132132'),
+      borderColor: active ? (theme?.buttonTextColor || '#ffffff') : (theme?.panelBorderColor || '#314e68'),
+    });
+  }
+  globalThis.aura.ui.endRow();
+  globalThis.aura.ui.endColumn();
+
+  let nextValue = value;
+  const states = [];
+  for (const option of normalizedOptions) {
+    const state = readViewState(`${rootId}-${option.id}`);
+    if (state?.clicked === true || state?.activated === true) {
+      nextValue = option.id;
+    }
+    states.push({
+      id: option.id,
+      label: option.label,
+      active: option.id === nextValue,
+      clicked: state?.clicked === true,
+      focused: state?.focused === true,
+      disabled: state?.disabled === true,
+    });
+  }
+
+  return {
+    ok: true,
+    reasonCode: 'ui_segmented_rendered',
+    value: nextValue,
+    changed: nextValue !== value,
+    options: states,
+  };
+}
+
+export function renderActionStrip({ id, actions = [] } = {}) {
+  if (!hasUiMethod('beginRow') || !hasUiMethod('button')) {
+    return {
+      ok: false,
+      reasonCode: 'ui_action_strip_runtime_unavailable',
+      actionId: null,
+    };
+  }
+  const normalizedActions = normalizeOptions(actions);
+  if (typeof id !== 'string' || id.trim().length <= 0 || normalizedActions.length <= 0) {
+    return {
+      ok: false,
+      reasonCode: 'ui_action_strip_invalid_actions',
+      actionId: null,
+    };
+  }
+
+  const rootId = id.trim();
+  globalThis.aura.ui.beginRow({
+    id: `${rootId}-actions`,
+    gap: 8,
+    width: 'fill',
+  });
+  for (const action of normalizedActions) {
+    globalThis.aura.ui.button(`${rootId}-${action.id}`, {
+      label: action.label,
+      width: 'fill',
+      disabled: action.disabled === true,
+    });
+  }
+  globalThis.aura.ui.endRow();
+
+  let actionId = null;
+  const states = [];
+  for (const action of normalizedActions) {
+    const state = readViewState(`${rootId}-${action.id}`);
+    if (state?.clicked === true || state?.activated === true) {
+      actionId = action.id;
+    }
+    states.push({
+      id: action.id,
+      clicked: state?.clicked === true,
+      focused: state?.focused === true,
+      disabled: state?.disabled === true,
+    });
+  }
+
+  return {
+    ok: true,
+    reasonCode: 'ui_action_strip_rendered',
+    actionId,
+    states: cloneSettingsValue(states),
+  };
+}
+
+export function listThemeSegmentOptions() {
+  return listUiThemeChoices();
+}
+
+export function listDensitySegmentOptions() {
+  return listUiDensityChoices();
+}
+
+export function listContrastSegmentOptions() {
+  return listUiContrastChoices();
+}
+
+export function formatPercentFromTenth(value) {
+  const numeric = Number(value);
+  const clamped = Number.isFinite(numeric) ? Math.max(0, Math.min(10, numeric)) : 0;
+  return `${Math.round(clamped * 10)}%`;
+}

package/src/runtime/ui-theme.js

@@ -0,0 +1,297 @@
+export const UI_THEME_SCHEMA = 'aurajs.ui-theme.v1';
+export const UI_PREFERENCES_SCHEMA = 'aurajs.ui-preferences.v1';
+
+const UI_THEME_PRESETS = Object.freeze({
+  'signal-dawn': Object.freeze({
+    id: 'signal-dawn',
+    label: 'Signal Dawn',
+    description: 'Warm amber callouts over slate control panels.',
+    theme: Object.freeze({
+      gap: 10,
+      padding: 12,
+      fontSize: 16,
+      lineHeight: 20,
+      buttonHeight: 38,
+      borderWidth: 1,
+      textColor: '#eef5ff',
+      mutedTextColor: '#9db2cb',
+      panelColor: '#0d1622',
+      panelBorderColor: '#314e68',
+      buttonColor: '#132132',
+      buttonHoverColor: '#203853',
+      buttonFocusColor: '#1e5b97',
+      buttonActiveColor: '#2183d6',
+      buttonTextColor: '#ffffff',
+    }),
+  }),
+  'midnight-arcade': Object.freeze({
+    id: 'midnight-arcade',
+    label: 'Midnight Arcade',
+    description: 'Neon cyan and magenta over a darker cabinet shell.',
+    theme: Object.freeze({
+      gap: 10,
+      padding: 12,
+      fontSize: 16,
+      lineHeight: 20,
+      buttonHeight: 38,
+      borderWidth: 1,
+      textColor: '#f5f8ff',
+      mutedTextColor: '#a9b4de',
+      panelColor: '#090d18',
+      panelBorderColor: '#4d3f82',
+      buttonColor: '#101728',
+      buttonHoverColor: '#21304f',
+      buttonFocusColor: '#7a49ff',
+      buttonActiveColor: '#f062d0',
+      buttonTextColor: '#ffffff',
+    }),
+  }),
+  'pine-night': Object.freeze({
+    id: 'pine-night',
+    label: 'Pine Night',
+    description: 'Forest greens and bright mint accents for readable HUDs.',
+    theme: Object.freeze({
+      gap: 10,
+      padding: 12,
+      fontSize: 16,
+      lineHeight: 20,
+      buttonHeight: 38,
+      borderWidth: 1,
+      textColor: '#eef7f2',
+      mutedTextColor: '#adc8bb',
+      panelColor: '#0b1713',
+      panelBorderColor: '#35584b',
+      buttonColor: '#13241e',
+      buttonHoverColor: '#1e3a31',
+      buttonFocusColor: '#2d7b63',
+      buttonActiveColor: '#4fb98c',
+      buttonTextColor: '#ffffff',
+    }),
+  }),
+});
+
+const UI_DENSITY_CHOICES = Object.freeze([
+  Object.freeze({ id: 'compact', label: 'Compact', description: 'Tighter gaps and shorter controls.' }),
+  Object.freeze({ id: 'cozy', label: 'Cozy', description: 'A roomier default for game settings screens.' }),
+]);
+
+const UI_CONTRAST_CHOICES = Object.freeze([
+  Object.freeze({ id: 'standard', label: 'Standard', description: 'Default contrast and chrome.' }),
+  Object.freeze({ id: 'high', label: 'High', description: 'Brighter text and stronger borders.' }),
+]);
+
+const DEFAULT_UI_PREFERENCES = Object.freeze({
+  schema: UI_PREFERENCES_SCHEMA,
+  themeId: 'signal-dawn',
+  density: 'cozy',
+  contrast: 'standard',
+  musicEnabled: true,
+  subtitlesEnabled: false,
+  masterVolume: 8,
+  reduceMotion: false,
+});
+
+function cloneUiValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneUiValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneUiValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+function clampNumber(value, min, max, fallback) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, numeric));
+}
+
+function normalizeChoice(value, choices, fallback) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  if (!normalized) return fallback;
+  return choices.some((entry) => entry.id === normalized) ? normalized : fallback;
+}
+
+function normalizeBoolean(value, fallback) {
+  if (value === true) return true;
+  if (value === false) return false;
+  return fallback;
+}
+
+function ensureUiBucket(appState) {
+  if (!appState || typeof appState !== 'object' || Array.isArray(appState)) {
+    throw new Error('Expected appState to be a mutable object.');
+  }
+  if (!appState.ui || typeof appState.ui !== 'object' || Array.isArray(appState.ui)) {
+    appState.ui = {};
+  }
+  return appState.ui;
+}
+
+function densityThemePatch(density) {
+  if (density === 'compact') {
+    return {
+      gap: 8,
+      padding: 10,
+      fontSize: 15,
+      lineHeight: 18,
+      buttonHeight: 34,
+    };
+  }
+  return {
+    gap: 12,
+    padding: 14,
+    fontSize: 16,
+    lineHeight: 20,
+    buttonHeight: 40,
+  };
+}
+
+function contrastThemePatch(contrast) {
+  if (contrast === 'high') {
+    return {
+      textColor: '#ffffff',
+      mutedTextColor: '#d4e1ff',
+      panelBorderColor: '#ffffff',
+      buttonFocusColor: '#ffffff',
+      buttonTextColor: '#08111b',
+    };
+  }
+  return {};
+}
+
+export function listUiThemeChoices() {
+  return Object.values(UI_THEME_PRESETS).map((entry) => ({
+    id: entry.id,
+    label: entry.label,
+    description: entry.description,
+  }));
+}
+
+export function listUiDensityChoices() {
+  return UI_DENSITY_CHOICES.map((entry) => ({ ...entry }));
+}
+
+export function listUiContrastChoices() {
+  return UI_CONTRAST_CHOICES.map((entry) => ({ ...entry }));
+}
+
+export function createUiPreferencesSeed(overrides = {}) {
+  const source = overrides && typeof overrides === 'object' && !Array.isArray(overrides)
+    ? overrides
+    : {};
+  return {
+    schema: UI_PREFERENCES_SCHEMA,
+    themeId: normalizeChoice(source.themeId, listUiThemeChoices(), DEFAULT_UI_PREFERENCES.themeId),
+    density: normalizeChoice(source.density, UI_DENSITY_CHOICES, DEFAULT_UI_PREFERENCES.density),
+    contrast: normalizeChoice(source.contrast, UI_CONTRAST_CHOICES, DEFAULT_UI_PREFERENCES.contrast),
+    musicEnabled: normalizeBoolean(source.musicEnabled, DEFAULT_UI_PREFERENCES.musicEnabled),
+    subtitlesEnabled: normalizeBoolean(source.subtitlesEnabled, DEFAULT_UI_PREFERENCES.subtitlesEnabled),
+    masterVolume: Math.round(clampNumber(source.masterVolume, 0, 10, DEFAULT_UI_PREFERENCES.masterVolume)),
+    reduceMotion: normalizeBoolean(source.reduceMotion, DEFAULT_UI_PREFERENCES.reduceMotion),
+  };
+}
+
+export function normalizeUiPreferences(source = null) {
+  const merged = source && typeof source === 'object' && !Array.isArray(source)
+    ? { ...DEFAULT_UI_PREFERENCES, ...source }
+    : { ...DEFAULT_UI_PREFERENCES };
+  return createUiPreferencesSeed(merged);
+}
+
+export function ensureUiPreferences(appState, seed = null) {
+  const ui = ensureUiBucket(appState);
+  const fallback = createUiPreferencesSeed(seed || {});
+  if (!ui.preferences || typeof ui.preferences !== 'object' || Array.isArray(ui.preferences)) {
+    ui.preferences = fallback;
+    return ui.preferences;
+  }
+  ui.preferences = normalizeUiPreferences({
+    ...fallback,
+    ...ui.preferences,
+  });
+  return ui.preferences;
+}
+
+export function updateUiPreferences(appState, patch = {}) {
+  const current = ensureUiPreferences(appState);
+  const next = normalizeUiPreferences({
+    ...current,
+    ...(patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {}),
+  });
+  const changedKeys = Object.keys(next).filter((key) => JSON.stringify(current[key]) !== JSON.stringify(next[key]));
+  ensureUiBucket(appState).preferences = next;
+  return {
+    ok: true,
+    reasonCode: changedKeys.length > 0 ? 'ui_preferences_updated' : 'ui_preferences_unchanged',
+    changedKeys,
+    preferences: cloneUiValue(next),
+  };
+}
+
+export function resetUiPreferences(appState, seed = null) {
+  const next = createUiPreferencesSeed(seed || {});
+  ensureUiBucket(appState).preferences = next;
+  return {
+    ok: true,
+    reasonCode: 'ui_preferences_reset',
+    preferences: cloneUiValue(next),
+  };
+}
+
+export function resolveUiTheme(preferences = null) {
+  const normalized = normalizeUiPreferences(preferences);
+  const preset = UI_THEME_PRESETS[normalized.themeId] || UI_THEME_PRESETS[DEFAULT_UI_PREFERENCES.themeId];
+  const theme = {
+    ...cloneUiValue(preset.theme),
+    ...densityThemePatch(normalized.density),
+    ...contrastThemePatch(normalized.contrast),
+  };
+  return {
+    schema: UI_THEME_SCHEMA,
+    reasonCode: 'ui_theme_ready',
+    presetId: preset.id,
+    presetLabel: preset.label,
+    density: normalized.density,
+    contrast: normalized.contrast,
+    preferences: cloneUiValue(normalized),
+    theme,
+    availableThemeIds: Object.keys(UI_THEME_PRESETS),
+  };
+}
+
+export function inspectUiTheme(appState) {
+  return resolveUiTheme(ensureUiPreferences(appState));
+}
+
+export function applyUiTheme(appState, { preferences = null } = {}) {
+  const themeState = preferences
+    ? resolveUiTheme(preferences)
+    : inspectUiTheme(appState);
+  const runtime = globalThis.aura;
+  if (!runtime?.ui || typeof runtime.ui.setTheme !== 'function') {
+    return {
+      ok: false,
+      reasonCode: 'ui_theme_runtime_unavailable',
+      themeState,
+    };
+  }
+  const result = runtime.ui.setTheme(themeState.theme);
+  if (result?.ok === false) {
+    return {
+      ok: false,
+      reasonCode: result.reasonCode || 'ui_theme_apply_failed',
+      themeState,
+    };
+  }
+  return {
+    ok: true,
+    reasonCode: result?.reasonCode || 'ui_theme_updated',
+    themeState,
+  };
+}

package/ui/hud.screen.js

@@ -0,0 +1,14 @@
+const hudScreen = {
+  id: 'hud',
+  kind: 'ui-screen',
+  anchors: [
+    { id: 'score', corner: 'top-left' },
+    { id: 'health', corner: 'top-right' },
+  ],
+  notes: [
+    'Gameplay HUD drawing still routes through the gameplay scene.',
+    'This authored screen keeps the example aligned with the scaffold folder contract.',
+  ],
+};
+
+export default hudScreen;