@lumen-mirror/core

The runtime for Lumen Mirror — a signal-driven framework for building smart mirror apps with TypeScript modules, HTML templates, and efficient DOM updates.

Install it in a mirror app (typically scaffolded with the lumen CLI):

npm install @lumen-mirror/core

Quick start

Bootstrap the runtime with a root selector and the modules you want to render:

import { lumen, ClockModule, WeatherModule } from './modules';

await lumen.bootstrap({
  root: '#app',
  modules: [ClockModule, WeatherModule],
});

Each module is a class decorated with @Module, backed by a template file and optional styles:

import { LumenModule, Module, signal } from '@lumen-mirror/core';

@Module({
  templateUrl: './clock.template.html',
  styleUrls: ['./clock.template.css'],
  host: {
    classes: ['clock'],
  },
})
export class ClockModule extends LumenModule {
  time = signal('12:00');

  onInit() {
    setInterval(() => {
      this.time.set(new Date().toLocaleTimeString());
    }, 1000);
  }
}

<!-- clock.template.html -->
<section>
  <h1>{{ time }}</h1>
</section>

Modules

Every mirror widget extends LumenModule. The renderer mounts each module as a custom element (e.g. <clock-module>) with an open shadow root. Template content and styleUrls live inside the shadow root; the element itself stays in the light DOM for grid layout and focus mode.

| Property / hook | Purpose | | --- | --- | | this.element | The custom-element host (light DOM) | | this.shadowRoot | Where the template is rendered — query this for dialog, popover, etc. | | onInit | After element / shadowRoot are assigned, before first paint | | onMount | After the element is connected to the document (connectedCallback) | | onPause / onResume | Focus mode visibility | | onDestroy | When the element is removed (disconnectedCallback) |

Scoped styles from styleUrls are injected via shared constructable stylesheets (adoptedStyleSheets) — they do not leak into other modules or the page.

Composition

Nest modules in templates with a self-closing tag. <WeatherModule /> compiles to <weather-module></weather-module>. The class name must match a module registered in bootstrap({ modules }):

<WeatherModule />
<ClockModule />

Templates

Templates are plain HTML with a small control-flow syntax. Bind signals with optional property paths — no arbitrary method calls.

<p>{{ weather().current.time }}</p>
<p>{{ summary }}</p>

Primitive values render as text. Objects and arrays cannot be interpolated directly (use @for / @in instead).

Interpolation

<p>{{ title }}</p>

Conditionals

@if(showDetails) {
  <p>{{ details }}</p>
} @else {
  <p>Hidden</p>
}

Lists

@for renders an array signal. Use track so the renderer can reuse DOM nodes when items reorder or update:

@for (todo of todos; track todo.id) {
  <li>{{ todo.label }}</li>
}

Without track, items are keyed by index.

Object entries

@in iterates object signal entries. Inside the block, use entry.key and entry.value:

@in (entry of settings) {
  <p>{{ entry.key }}: {{ entry.value }}</p>
}

Signals

@lumen-mirror/core re-exports the signal toolkit from @chocosd/node-signals. Declare signals as properties on your module class; the template binder reads them automatically.

import { signal, computed, createEffect } from '@lumen-mirror/core';

export class WeatherModule extends LumenModule {
  temp = signal(72);
  label = computed(() => `${this.temp()}°F`);
}

Useful exports include signal, computed, createEffect, batch, from, fromHttp, and operators like debounceTime and distinctUntilChanged.

Templates only accept signal references (and loop variables like item or entry.key). Anything more complex belongs in the module class.

Host styling

Each module has a host controller for dynamic classes, attributes, and inline styles on its wrapper element:

this.host.addClass('fullscreen');
this.host.setAttribute('data-mode', 'minimal');
this.host.setStyle('opacity', '0.5');

Static host options can also be set in the @Module decorator.

Host interaction

Optional hooks on the module class are wired to the host element automatically:

onClick(event: MouseEvent) {
  this.host.addClass('active');
}

onHover(hovering: boolean) {
  // true on pointer enter, false on leave
}

onFocus(event: FocusEvent) { /* focusin */ }
onBlur(event: FocusEvent) { /* focusout */ }

onClick uses the native click event (mouse and touch/tap). Listeners are removed when the module is destroyed.

Template event bindings

Bind DOM events to module methods directly in the template with (event)="method(...)", similar to Angular. Unlike {{ }} interpolations, handler expressions may call methods and pass arguments.

<button (click)="openSettings()">Settings</button>
<button (click)="navTo('alarms')">Alarms</button>

@for (alarm of alarms; track alarm.id) {
  <button (click)="editAlarm(alarm.id)">{{ alarm.time }}</button>
}

<form (submit)="save($event)"> … </form>

Arguments can be:

• $event — the DOM event
• string / number / boolean / null literals
• a property path from the loop scope (alarm.id) or the module (signals are unwrapped)

(click) maps to the native click event (keyboard activation included, so it's accessible). (hover) maps to pointerenter + pointerleave. Any other (name) maps to the matching native event (input, change, submit, …). Listeners are removed when the block or module is destroyed.

Cross-module events

Modules communicate imperatively through a shared event bus — useful for things like fullscreen mode, processing state, or pausing background work in other widgets.

Each module receives this.events before onInit. It's a per-module facade over the shared bus: emits are tagged with the emitting module automatically, and subscriptions are tracked and disposed on destroy — no manual unsubscribe() in onDestroy.

Handlers receive an envelope { event, payload, source }. source is { id, name } for the emitting module, or null for events emitted on the root bus.

// WeatherModule — emit when going fullscreen (source is attached for you)
onClick() {
  this.events.emit('weather:fullscreen', true);
}

// SocketModule — react in TS, not in the template
onInit() {
  this.events.on('weather:fullscreen', ({ payload, source }) => {
    console.log(`${source?.name ?? 'system'} toggled fullscreen`);
    if (payload) this.pausePolling();
    else this.resumePolling();
  });
}

To keep a subscription past the module's lifetime, opt out of automatic teardown and manage it yourself:

const off = this.events.on('tick', handler, { manualDispose: true });
// ... call off() when you're done

Recent emissions from a module are available for debugging via this.events.emissions.

To react to your own signal changes and broadcast them, combine signals with createEffect:

onInit() {
  createEffect(() => {
    this.events.emit('weather:mode', this.mode());
  });
}

Runtime API

lumen.bootstrap(config) returns a LumenRuntime:

const runtime = await lumen.bootstrap({ root: '#app', modules: [...] });

runtime.registry;  // ModuleRegistry
runtime.eventBus;  // shared EventBus instance
runtime.bindings;  // root binding collection

runtime.destroy(); // tear down DOM and subscriptions

Lower-level renderer and binding utilities are also exported for advanced use and testing.

Package details

• ESM only — "type": "module"
• Peer environment — browser DOM APIs (document, fetch for templates)
• Dependency — @chocosd/node-signals

For scaffolding apps and modules, install the @lumen-mirror/cli package:

npm install -g @lumen-mirror/cli
lumen new my-mirror