Idevice

iDevice development

Read the target under public/files/perm/idevices/base/, its config.xml, edition/export scripts, colocated tests, and public/app/workarea/idevices/. Use the nearest comparable iDevice, not a generic scaffold. checklist, rubric and geogebra-activity show legacy patterns; slide/src/ shows a bundled TypeScript editor already in main (scripts/build-slide-editor.ts). Do not assume other branches' migrations landed.

Trace the complete lifecycle

• Follow config discovery → edition initialization → validation/save → persisted HTML/data → reload → preview/export initialization → teardown. Preserve the actual $exeDevice/runtime globals and hooks. Methods vary (loadPreviousValues, updateFieldGame, etc.); there is no universal loadData() contract.
• The test must round-trip every changed field, including empty/default values and a real legacy fixture. If stored data uses escaped/encrypted JSON or versioned attributes, keep its existing encoding contract; do not prescribe escape() for a new format or decode historical data twice.
• Preserve IDs, config metadata, icon references, edition/export resource names and library registration. Prevent repeated .exe-text wrappers on re-import through the existing normalization path.
• Test exported behavior independently of the workarea's globals and DOM. Multiple instances on one page need isolated IDs/state; preview and the exported ZIP must include all required resources.
• Dispose listeners, timers, media/canvas resources and object URLs through this.$lifecycle (below); TinyMCE editors in the form are disposed centrally. Check switching devices and leaving edition; do not overwrite another device's global or discard unsaved work during a remote Yjs refresh.
• Use _() for editor controls and c_() for learning content, preserving the project's content locale. Retain keyboard controls, labels, focus and feedback in edition and exported activities.

Edition lifecycle: own what you create

An editor is opened and closed many times in one session. Anything the edition creates that can outlive its form — a timer, a handler on document, a player, a pending read — must be owned by the edition's lifecycle, or it keeps running after the editor is gone and, worse, can end up driving the next iDevice the user opens.

IdeviceNode gives every edition an EditionLifecycle (public/app/workarea/project/idevices/content/editionLifecycle.js) before calling init(), as this.$lifecycle. Register through it and teardown is automatic. See ADR-2293-01.

init: function (element, data) {
    // Timers: cancelled on close. `this` is this edition instance.
    this.$lifecycle.setInterval(function () { this.refreshPreview(); }, 1000);

    // Handlers on shared targets: removed on close, by a namespace unique to
    // this edition, so unrelated handlers on document/window are untouched.
    this.$lifecycle.on(document, 'keydown', this.onKeyDown);

    // Native listeners: removed through the lifecycle's AbortSignal.
    this.$lifecycle.addEventListener(window, 'resize', this.onResize);

    // Anything with its own cleanup API — name the method, never assume one.
    this.$lifecycle.ownInstance(player, 'destroy');   // YouTube player
    this.$lifecycle.ownInstance(observer, 'disconnect');
    this.$lifecycle.ownMedia(audioElement);           // pause + release the stream
    this.$lifecycle.own(() => URL.revokeObjectURL(blobUrl));
    this.$lifecycle.ownFileReader(reader);            // abort an in-flight read
    this.$lifecycle.own(() => widget.teardown());     // anything else

    // Abortable requests, and file reads that always settle.
    fetch(url, { signal: this.$lifecycle.signal });
    const text = await this.$lifecycle.readFile(file, 'readAsText');
}

A resource the edition rebuilds on every user action — the audio preview, say — must name a slot, or each action leaves one more live resource and one more disposer behind until the editor closes. Owning into a slot releases whatever that slot held:

this.$lifecycle.ownMedia(new Audio(url), 'previewAudio');

Wrapping a FileReader in a promise by hand is the one case the primitives get wrong on their own: abort() fires no error event and a bound loadend no-ops, so the promise never settles and the caller awaits it for the lifetime of the page. Use readFile(file, method), which rejects with an AbortError on teardown exactly as an aborted fetch() does.