@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/platform/guide-intensity.d.ts

@@ -1,39 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** What the guide sounds like, for a given distance. */
-export interface Intensity {
-    /** The low-pass cutoff, in hertz. Low and muffled far away; open and bright up close. */
-    readonly cutoff: number;
-    /** A factor on the `guide` category's volume, between `FAR_VOL` and 1. NEVER zero. */
-    readonly volume: number;
-}
-/**
- * From how many steps on the guide stops getting darker.
- *
- * Twelve, and the number is not new: the sonar's distance words cut "very near" at 4 steps and "near" at 9, and its pan
- * saturates the stereo at 11. The guide saturates just after — fine detail serves whoever is arriving, and beyond that
- * "far" is enough.
- */
-export declare const STEPS_TO_FLOOR = 12;
-/** The cutoff at the bottom of the scale: muffled, present, never an alarm sound. */
-export declare const FAR_CUT = 320;
-/** The cutoff at the target: open. Above this the timbre starts to hiss, and a hiss draws attention like a beep. */
-export declare const NEAR_CUT = 3200;
-/**
- * The lowest volume factor.
- *
- * ⚠️ NEVER ZERO, AND IT IS THE MOST IMPORTANT ASSERTION IN THIS FILE. If the guide went mute far away, "far" would be
- * indistinguishable from "there is no target" — and the child who depends on it would conclude there is nothing to find,
- * exactly when there is and it is distant. Silence is a statement, and here it would be a false one.
- */
-export declare const FAR_VOL = 0.55;
-/**
- * The intensity for `stepsAway` steps along the route.
- *
- * ⚠️ THE CUTOFF INTERPOLATES EXPONENTIALLY, not linearly, for the reason of #124's earcon: the ear perceives pitch and
- * brightness as a RATIO, not a difference. A linear ramp from 320 to 3200 would open almost everything in the first third
- * of the way and then seem to stand still — the child would feel they had arrived with half the way to go.
- *
- * The volume interpolates LINEARLY, and the asymmetry is deliberate: it is the secondary axis, and an exponential curve
- * there too would make both accelerate at the same point, the opposite of having two axes.
- */
-export declare function guideIntensity(stepsAway: number): Intensity;

package/dist-pkg/platform/guide-intensity.js

@@ -1,71 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// platform/guide-intensity — HOW NEAR IT SOUNDS, without a beep (#84 item 2).
-//
-// ========================= WHAT THIS REPLACES =========================
-// The guide used to play a beep at a fixed interval, FOREVER, whether or not anything moved. The Dev's verdict: «um ping
-// é a pior escolha possível, tenebroso para quem tem TEA». It was not the frequency that was wrong — it was the beep.
-// Playing it "only while walking" would have left the same thing hurting less often.
-//
-// What replaces it is a CONTINUOUS presence that grows more intense as the child approaches, along the mapped route
-// (`core/route`). Nothing fires; the sound simply becomes more present.
-//
-// ========================= THE AXIS IS BRIGHTNESS, AND THE DECISION IS THE DEV'S =========================
-// Four axes were put on the table — volume, brightness (filter cutoff), layers and tempo — and the choice was
-// **brightness as the main one, with a small share of volume as secondary**. The reasons, for whoever reopens it:
-//
-//   · VOLUME ALONE collides with the mixer's slider: a child who turned the `guide` category down would lose the whole
-//     signal, and volume change is the most tiring of the four.
-//   · TEMPO reads as HURRY, the opposite of what autism-support mode exists to protect.
-//   · LAYERS needs composed material, and this engine synthesises.
-//   · BRIGHTNESS is continuous, comes from a `BiquadFilter` Web Audio already has, and does not fight the slider.
-//
-// ⚠️ AND THE SHARE OF VOLUME IS NOT DECORATION: for a child with hearing loss the brightness may fall exactly in the band
-// they cannot reach. Two redundant axes mean neither decides alone.
-//
-// ========================= WHAT THIS MODULE DOES NOT DO =========================
-// It plays nothing. It returns two numbers from ONE: how many steps remain along the route. Whoever builds the graph
-// plays them, and `core/route` computes the route — it already knows how to go round a wall, and that is what makes the
-// intensity honest: it grows with the distance the child will REALLY walk.
-//
-// A leaf module: it imports nothing.
-/**
- * From how many steps on the guide stops getting darker.
- *
- * Twelve, and the number is not new: the sonar's distance words cut "very near" at 4 steps and "near" at 9, and its pan
- * saturates the stereo at 11. The guide saturates just after — fine detail serves whoever is arriving, and beyond that
- * "far" is enough.
- */
-export const STEPS_TO_FLOOR = 12;
-/** The cutoff at the bottom of the scale: muffled, present, never an alarm sound. */
-export const FAR_CUT = 320;
-/** The cutoff at the target: open. Above this the timbre starts to hiss, and a hiss draws attention like a beep. */
-export const NEAR_CUT = 3200;
-/**
- * The lowest volume factor.
- *
- * ⚠️ NEVER ZERO, AND IT IS THE MOST IMPORTANT ASSERTION IN THIS FILE. If the guide went mute far away, "far" would be
- * indistinguishable from "there is no target" — and the child who depends on it would conclude there is nothing to find,
- * exactly when there is and it is distant. Silence is a statement, and here it would be a false one.
- */
-export const FAR_VOL = 0.55;
-/**
- * The intensity for `stepsAway` steps along the route.
- *
- * ⚠️ THE CUTOFF INTERPOLATES EXPONENTIALLY, not linearly, for the reason of #124's earcon: the ear perceives pitch and
- * brightness as a RATIO, not a difference. A linear ramp from 320 to 3200 would open almost everything in the first third
- * of the way and then seem to stand still — the child would feel they had arrived with half the way to go.
- *
- * The volume interpolates LINEARLY, and the asymmetry is deliberate: it is the secondary axis, and an exponential curve
- * there too would make both accelerate at the same point, the opposite of having two axes.
- */
-export function guideIntensity(stepsAway) {
-    if (!Number.isFinite(stepsAway) || stepsAway < 0)
-        return { cutoff: FAR_CUT, volume: FAR_VOL };
-    // 0 = right on the target; 1 = at the bottom of the scale or beyond.
-    const far = Math.min(1, stepsAway / STEPS_TO_FLOOR);
-    const near = 1 - far;
-    return {
-        cutoff: FAR_CUT * Math.pow(NEAR_CUT / FAR_CUT, near),
-        volume: FAR_VOL + (1 - FAR_VOL) * near,
-    };
-}

package/dist-pkg/ui/latch-refusal.d.ts

@@ -1,33 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-/** A line ready to translate. `null` = there is a choice, and nothing to say. */
-export interface LatchRefusal {
-    readonly key: string;
-    /** The transport that requires it — available to whoever wants to compose the sentence another way. */
-    readonly transport: string;
-}
-/**
- * The i18n key of the reason, PER TRANSPORT.
- *
- * ⚠️ FOUR KEYS AND NOT ONE WITH `{aparelho}`, and the reason is translation, not style: «os gestos» is plural and
- * «o olhar» is not, so a single sentence would force each language to build agreement from a loose noun. It is
- * exactly the defect `sr.nav.clockOne` recorded for «às 1 horas», and that `ui/simulation-refusal` already refused
- * for the same reason with its three axes.
- */
-export declare const REFUSAL_KEY: Readonly<Record<string, string>>;
-/**
- * Can latching be turned off on this device? And if not, what to say.
- *
- * `null` = it can; the interface shows nothing, because a warning that always appears stops being read.
- */
-export declare function latchRefusal(transportName: string): LatchRefusal | null;
-/**
- * Does the control stay ON SCREEN when latching is required?
- *
- * ⚠️ ALWAYS, and it is the "does not disappear" half of clause 3. It exists as a function with its own name, and
- * not as a negated refusal at the point of use, because it answers another question: `latchRefusal` says *why* it
- * cannot; this says *that the row stays on screen*. Merging them would make "no reason" look like "do not draw the
- * row".
- */
-export declare function showsEvenWhenRequired(): boolean;
-/** The transports that require latching, for whoever needs to enumerate them. It comes from the RULE, not a copy. */
-export declare const NEED_LATCH: ReadonlySet<string>;

package/dist-pkg/ui/latch-refusal.js

@@ -1,60 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/latch-refusal.ts — WHEN LATCHING IS NOT A CHOICE, and what to say to whoever pressed the button.
-//
-// ========================= CLAUSE 3 OF ADR-0113 =========================
-// «É impossível desligá-la em modos que não tem como funcionar sem ela (voz e câmera)» — the Dev's sentence. With
-// eyes, face, gestures and speech, latching is what makes the input work: without it, one command at a time means
-// the child cannot move and act.
-//
-// ⚠️ AND THE CONTROL DOES NOT DISAPPEAR — IT IS DISABLED, WITH THE REASON SAID. Disappearing teaches that the thing
-// does not exist: an adult concludes it was removed, not that the webcam requires it. It is the same «never silently
-// removed» half that ADR-0076 wrote for the simulation, and this file is the sibling of `ui/simulation-refusal` on
-// purpose — same shape, same place in the layer, and so checkable in the `node` project, with no document.
-//
-// 🔴 AND THE REASON IS A FACT ABOUT THE DEVICE, NEVER A REPRIMAND. "Gaze control needs tap-to-move to work." says why
-// the button does not respond; telling the child not to turn it off scolds them for touching a setting they depend
-// on. ADR-0076 already paid for this distinction once.
-//
-// Leaf module: it imports only the pure latching rule.
-import { latchIsOptional, ONE_COMMAND_AT_A_TIME } from '../input/latch-scope.js';
-/**
- * The i18n key of the reason, PER TRANSPORT.
- *
- * ⚠️ FOUR KEYS AND NOT ONE WITH `{aparelho}`, and the reason is translation, not style: «os gestos» is plural and
- * «o olhar» is not, so a single sentence would force each language to build agreement from a loose noun. It is
- * exactly the defect `sr.nav.clockOne` recorded for «às 1 horas», and that `ui/simulation-refusal` already refused
- * for the same reason with its three axes.
- */
-export const REFUSAL_KEY = Object.freeze({
-    olhos: 'alt.exigida.olhos',
-    rosto: 'alt.exigida.rosto',
-    gestos: 'alt.exigida.gestos',
-    fala: 'alt.exigida.fala',
-});
-/**
- * Can latching be turned off on this device? And if not, what to say.
- *
- * `null` = it can; the interface shows nothing, because a warning that always appears stops being read.
- */
-export function latchRefusal(transportName) {
-    if (latchIsOptional(transportName))
-        return null;
-    const refusalKey = REFUSAL_KEY[transportName];
-    // 📌 A transport that requires latching and has no sentence would be a button disabled WITHOUT a reason — worse
-    // than the defect this fixes, because the child would not even know there is a reason. The gate asserts that the
-    // two sets match; here the absence degrades to "do not refuse", which keeps the control alive.
-    return refusalKey ? { key: refusalKey, transport: transportName } : null;
-}
-/**
- * Does the control stay ON SCREEN when latching is required?
- *
- * ⚠️ ALWAYS, and it is the "does not disappear" half of clause 3. It exists as a function with its own name, and
- * not as a negated refusal at the point of use, because it answers another question: `latchRefusal` says *why* it
- * cannot; this says *that the row stays on screen*. Merging them would make "no reason" look like "do not draw the
- * row".
- */
-export function showsEvenWhenRequired() {
-    return true;
-}
-/** The transports that require latching, for whoever needs to enumerate them. It comes from the RULE, not a copy. */
-export const NEED_LATCH = ONE_COMMAND_AT_A_TIME;