@wyndlass/app-sdk 0.0.0-stage → 1.0.0

package/dist/contract/player-api-event.d.ts

@@ -0,0 +1,253 @@
+/**
+ * An event the controller emits (protocol/player-api.json, ADR 0050): to apps that subscribed on the screen, and in the ring player.events reads. Told apart by type.
+ */
+export type PlayerAPIEvent = StateChanged | ContentUpdated | ItemStart | ItemEnd | ItemError | ConnectionChanged | AudioChanged | DisplayChanged | TimeChanged | AppCommand | AppFailed | AppHeld;
+/**
+ * RFC 3339 timestamp with offset.
+ */
+export type CommonTimestamp = string;
+/**
+ * idle: nothing to play; stopped: the standby screen.
+ */
+export type PlayerApiStatusState = "starting" | "playing" | "paused" | "stopped" | "idle" | "error";
+/**
+ * Who caused a change: the player itself, an app on the screen, or a remote caller whose principal core relayed.
+ */
+export type PlayerApiCommonBy = {
+    kind: "player";
+} | {
+    kind: "app";
+    /**
+     * The app's id (app-definition).
+     */
+    app: string;
+    instance: string;
+} | {
+    kind: "remote";
+    principal: CommonPrincipalRef;
+};
+/**
+ * A principal, e.g. user:u_123, agent:fleet-guardian, device:dev_...
+ */
+export type CommonPrincipalRef = string;
+/**
+ * Lowercase hex SHA-256 digest.
+ */
+export type CommonSha256 = string;
+/**
+ * A zone of the screen; main until compositions have zones.
+ */
+export type PlayerApiCommonZone = string;
+/**
+ * Media item id (asset, app, composition, playlist or live source).
+ */
+export type CommonMediaId = string;
+/**
+ * Whether the player is connected to Wyndlass (NATS).
+ */
+export type PlayerApiCommonConnection = "online" | "offline";
+/**
+ * The app's id (app-definition), where the layout carries it (appInfo).
+ */
+export type AppId = string;
+/**
+ * The app's element, as a path of element ids from the outermost layout (ADR 0053, decision 13).
+ */
+export type ElementPath = string;
+export interface StateChanged {
+    type: "state.changed";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    state: PlayerApiStatusState;
+    previous: PlayerApiStatusState;
+    by: PlayerApiCommonBy;
+}
+export interface ContentUpdated {
+    type: "content.updated";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    manifest: CommonSha256;
+    previous?: CommonSha256;
+}
+export interface ItemStart {
+    type: "item.start";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    zone: PlayerApiCommonZone;
+    item: CommonItemRef;
+    blob: CommonSha256;
+    contentType: string;
+    startedAt: CommonTimestamp;
+    durationMs?: number;
+    /**
+     * The transition the item's entry asked for and the one the player played (WP-0056): a crossfade it could not play, between two native videos on a host that holds one, plays as a cut. Absent when the entry asked for none.
+     */
+    transition?: {
+        asked: "cut" | "crossfade";
+        played: "cut" | "crossfade";
+    };
+    /**
+     * The layout element the item plays in, as a path of element ids from the outermost layout (ADR 0053, decision 13; WP-0056); `loop` for a playlist playing on its own. Absent for the screen's own loop.
+     */
+    element?: string;
+}
+/**
+ * A pinned reference to a media item version.
+ */
+export interface CommonItemRef {
+    id: CommonMediaId;
+    version: number;
+}
+export interface ItemEnd {
+    type: "item.end";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    zone: PlayerApiCommonZone;
+    item: CommonItemRef;
+    blob: CommonSha256;
+    endedAt: CommonTimestamp;
+    /**
+     * replaced: a new manifest; finished: the app ended its slot.
+     */
+    reason: "completed" | "skipped" | "stopped" | "error" | "replaced" | "finished";
+    /**
+     * The layout element the item plays in, as a path of element ids from the outermost layout (ADR 0053, decision 13; WP-0056); `loop` for a playlist playing on its own. Absent for the screen's own loop.
+     */
+    element?: string;
+}
+export interface ItemError {
+    type: "item.error";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    zone: PlayerApiCommonZone;
+    item: CommonItemRef;
+    blob: CommonSha256;
+    code: string;
+    message: string;
+}
+export interface ConnectionChanged {
+    type: "connection.changed";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    connection: PlayerApiCommonConnection;
+}
+export interface AudioChanged {
+    type: "audio.changed";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    audio: PlayerApiCommonAudio;
+    by: PlayerApiCommonBy;
+}
+/**
+ * The player's own level, not the operating system's.
+ */
+export interface PlayerApiCommonAudio {
+    volume: number;
+    muted: boolean;
+}
+export interface DisplayChanged {
+    type: "display.changed";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    display: PlayerApiCommonDisplay;
+    by: PlayerApiCommonBy;
+}
+export interface PlayerApiCommonDisplay {
+    power: "on" | "standby" | "unknown";
+    brightness?: number;
+}
+export interface TimeChanged {
+    type: "time.changed";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    reason: "clock-adjusted" | "time-zone-changed";
+}
+export interface AppCommand {
+    type: "app.command";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    name: string;
+    /**
+     * Any JSON the sender gave.
+     */
+    argument?: {
+        [k: string]: unknown | undefined;
+    };
+    by: PlayerApiCommonBy;
+}
+/**
+ * An app on the screen could not run, or misbehaved (WP-0100). The rest of its layout plays on.
+ */
+export interface AppFailed {
+    type: "app.failed";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    item: CommonItemRef1;
+    app?: AppId;
+    element?: ElementPath;
+    /**
+     * load: its bundle did not import. shape: it exports no element class the host can define, or (a customer's app) no way to take its context. unsupported: it needs a newer Player API or WebView than this screen has, or it is a customer's app and this screen's page was never handed its port (WP-0100 part b). error: it threw three times in a minute, and was stopped. late: it was not ready by its deadline, and shows as it is. overran: an enter or exit ran past its clip.
+     */
+    reason: "load" | "shape" | "unsupported" | "error" | "late" | "overran";
+    /**
+     * The name of what it threw (TypeError), for error, load and shape. Never its message, which could carry anything the app holds.
+     */
+    error?: string;
+}
+/**
+ * A pinned reference to a media item version.
+ */
+export interface CommonItemRef1 {
+    id: CommonMediaId;
+    version: number;
+}
+/**
+ * An app version held back on this screen until the next manifest, after the page stopped answering twice within an hour while it was on screen (WP-0100). Its element is drawn empty meanwhile.
+ */
+export interface AppHeld {
+    type: "app.held";
+    /**
+     * The event's place in this player's sequence since it started; player.events pages by it.
+     */
+    seq: number;
+    at: CommonTimestamp;
+    item: CommonItemRef;
+    app?: AppId;
+    /**
+     * How many times the page stopped answering in the last hour with this app on screen.
+     */
+    hangs: number;
+}

package/dist/contract/player-api-event.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/player-api-event.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/player-api-status.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Device id.
+ */
+export type CommonDeviceId = string;
+export type CommonSemver = string;
+/**
+ * IANA time zone name.
+ */
+export type CommonTimeZone = string;
+/**
+ * BCP 47 language tag.
+ */
+export type CommonLocale = string;
+/**
+ * Whether the player is connected to Wyndlass (NATS).
+ */
+export type PlayerApiCommonConnection = "online" | "offline";
+/**
+ * idle: nothing to play; stopped: the standby screen.
+ */
+export type State = "starting" | "playing" | "paused" | "stopped" | "idle" | "error";
+/**
+ * Who caused a change: the player itself, an app on the screen, or a remote caller whose principal core relayed.
+ */
+export type PlayerApiCommonBy = {
+    kind: "player";
+} | {
+    kind: "app";
+    /**
+     * The app's id (app-definition).
+     */
+    app: string;
+    instance: string;
+} | {
+    kind: "remote";
+    principal: CommonPrincipalRef;
+};
+/**
+ * A principal, e.g. user:u_123, agent:fleet-guardian, device:dev_...
+ */
+export type CommonPrincipalRef = string;
+/**
+ * RFC 3339 timestamp with offset.
+ */
+export type CommonTimestamp = string;
+/**
+ * Lowercase hex SHA-256 digest.
+ */
+export type CommonSha256 = string;
+/**
+ * RFC 3339 timestamp with offset.
+ */
+export type CommonTimestamp1 = string;
+/**
+ * A zone of the screen; main until compositions have zones.
+ */
+export type PlayerApiCommonZone = string;
+/**
+ * Media item id (asset, app, composition, playlist or live source).
+ */
+export type CommonMediaId = string;
+/**
+ * Everything the controller knows about the player at once: player.status's result, and what apps read through their controller (protocol/player-api.json, ADR 0050).
+ */
+export interface PlayerAPIStatus {
+    apiVersion: number;
+    device: PlayerApiCommonDeviceFacts;
+    /**
+     * Where player-core runs; in preview and the designer, commands change nothing.
+     */
+    mode: "player" | "preview" | "designer";
+    timeZone: CommonTimeZone;
+    locale: CommonLocale;
+    connection: PlayerApiCommonConnection;
+    state: State;
+    held?: Held;
+    content?: Content;
+    /**
+     * What each zone shows.
+     *
+     * @maxItems 64
+     */
+    now: NowItem[];
+    audio?: PlayerApiCommonAudio;
+    display?: PlayerApiCommonDisplay;
+    capabilities: PlayerApiCommonHostCapabilities;
+}
+/**
+ * What the host says the device is; fixed while the player runs.
+ */
+export interface PlayerApiCommonDeviceFacts {
+    id: CommonDeviceId;
+    /**
+     * The device type (protocol/device-types).
+     */
+    type: string;
+    /**
+     * Which shell hosts player-core.
+     */
+    shell: "android" | "universal-electron" | "universal-brightsign" | "wpf" | "webos" | "simulator";
+    shellVersion: CommonSemver;
+    coreVersion: CommonSemver;
+    model?: string;
+    resolution: PlayerApiCommonResolution;
+    orientation: "landscape" | "portrait";
+}
+export interface PlayerApiCommonResolution {
+    width: number;
+    height: number;
+}
+/**
+ * A remote pause or stop in effect: apps' playback commands are refused with HELD until a remote play or a restart (ADR 0050).
+ */
+export interface Held {
+    by: PlayerApiCommonBy;
+    since: CommonTimestamp;
+}
+/**
+ * The manifest playing; absent when there is none.
+ */
+export interface Content {
+    manifest: CommonSha256;
+    issuedAt: CommonTimestamp;
+    switchedAt: CommonTimestamp;
+    windowTo?: CommonTimestamp1;
+    /**
+     * The window has ended: the player plays this content until a newer manifest arrives (WP-0053).
+     */
+    stale?: boolean;
+}
+export interface NowItem {
+    zone: PlayerApiCommonZone;
+    item: CommonItemRef;
+    blob: CommonSha256;
+    contentType: string;
+    startedAt: CommonTimestamp;
+    durationMs?: number;
+    positionMs?: number;
+}
+/**
+ * A pinned reference to a media item version.
+ */
+export interface CommonItemRef {
+    id: CommonMediaId;
+    version: number;
+}
+/**
+ * The player's own level, not the operating system's.
+ */
+export interface PlayerApiCommonAudio {
+    volume: number;
+    muted: boolean;
+}
+export interface PlayerApiCommonDisplay {
+    power: "on" | "standby" | "unknown";
+    brightness?: number;
+}
+/**
+ * What the host can do beyond the controller's own; tools that need what it lacks are not listed.
+ */
+export interface PlayerApiCommonHostCapabilities {
+    /**
+     * The player's volume and mute can be set.
+     */
+    audio: boolean;
+    /**
+     * With audio, whether the volume can be set to a level (audio.setVolume). False where only mute can: the Amazon Signage Stick, whose API sets no level on any TV (WP-0096 part g). Absent means it can.
+     */
+    volume?: boolean;
+    display: {
+        power: boolean;
+        brightness: boolean;
+        /**
+         * The host turns its whole output, native surfaces included, by the system (ADR 0052, decision 4): host.setDisplay's rotation. Without it, the page turns itself (WP-0056 part d).
+         */
+        rotation?: boolean;
+    };
+}

package/dist/contract/player-api-status.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/player-api-status.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/easing.d.ts

@@ -0,0 +1,16 @@
+/** A CSS easing name or cubic-bezier(a, b, c, d) as a cubic Bézier; `ease` when absent or unreadable. */
+export declare function easingOf(name: string | undefined): readonly number[];
+/**
+ * The cubic Bézier `easing` at x, as browsers solve it: x(t) inverted by Newton's method, then bisection, to 1e-7; then
+ * y at that t. 0 before 0 and 1 after 1.
+ */
+export declare function cubicBezier(easing: readonly number[], x: number): number;
+/**
+ * When each of n items animates in a staggered enter or exit (ADR 0071, decision 4): item i starts i × stagger after
+ * the start, and every item runs for what is left, so the last ends with the whole. The stagger is shortened, to whole
+ * milliseconds, where it would leave an item less than 16 ms (one frame).
+ */
+export declare function staggerTimes(startMs: number, durationMs: number, staggerMs: number | undefined, n: number): {
+    startMs: number;
+    endMs: number;
+}[];

package/dist/easing.js

@@ -0,0 +1,71 @@
+// The presets' curves (WP-0101 decision 2): the SDK's own, so it imports nothing of player-core's. Both give every case
+// of protocol/test-vectors/easing.json, so an app's enter and exit move as the layout's clips around it do.
+const NAMED = {
+    linear: [0, 0, 1, 1], ease: [0.25, 0.1, 0.25, 1], "ease-in": [0.42, 0, 1, 1], "ease-out": [0, 0, 0.58, 1], "ease-in-out": [0.42, 0, 0.58, 1],
+};
+/** A CSS easing name or cubic-bezier(a, b, c, d) as a cubic Bézier; `ease` when absent or unreadable. */
+export function easingOf(name) {
+    if (!name)
+        return NAMED.ease;
+    if (NAMED[name])
+        return NAMED[name];
+    const m = /^cubic-bezier\(\s*([^,]+),\s*([^,]+),\s*([^,]+),\s*([^)]+)\)$/.exec(name);
+    const v = m?.slice(1).map(Number);
+    return v && v.every(Number.isFinite) ? v : NAMED.ease;
+}
+/**
+ * The cubic Bézier `easing` at x, as browsers solve it: x(t) inverted by Newton's method, then bisection, to 1e-7; then
+ * y at that t. 0 before 0 and 1 after 1.
+ */
+export function cubicBezier(easing, x) {
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const [x1, y1, x2, y2] = easing;
+    if (x1 === y1 && x2 === y2)
+        return x;
+    const cx = 3 * x1, bx = 3 * (x2 - x1) - cx, ax = 1 - cx - bx;
+    const cy = 3 * y1, by = 3 * (y2 - y1) - cy, ay = 1 - cy - by;
+    const sampleX = (t) => ((ax * t + bx) * t + cx) * t;
+    const sampleY = (t) => ((ay * t + by) * t + cy) * t;
+    const slopeX = (t) => (3 * ax * t + 2 * bx) * t + cx;
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+        const err = sampleX(t) - x;
+        if (Math.abs(err) < 1e-7)
+            return sampleY(t);
+        const d = slopeX(t);
+        if (Math.abs(d) < 1e-6)
+            break;
+        t -= err / d;
+    }
+    let lo = 0, hi = 1;
+    t = x;
+    while (lo < hi) {
+        const v = sampleX(t);
+        if (Math.abs(v - x) < 1e-7)
+            break;
+        if (x > v)
+            lo = t;
+        else
+            hi = t;
+        t = (hi - lo) / 2 + lo;
+        if (hi - lo < 1e-7)
+            break;
+    }
+    return sampleY(t);
+}
+/**
+ * When each of n items animates in a staggered enter or exit (ADR 0071, decision 4): item i starts i × stagger after
+ * the start, and every item runs for what is left, so the last ends with the whole. The stagger is shortened, to whole
+ * milliseconds, where it would leave an item less than 16 ms (one frame).
+ */
+export function staggerTimes(startMs, durationMs, staggerMs, n) {
+    if (n <= 0)
+        return [];
+    const most = n > 1 ? Math.floor(Math.max(0, durationMs - 16) / (n - 1)) : 0;
+    const s = Math.min(staggerMs ?? 0, most);
+    const each = durationMs - (n - 1) * s;
+    return Array.from({ length: n }, (_, i) => ({ startMs: startMs + i * s, endMs: startMs + i * s + each }));
+}

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The app runtime (WP-0101, ADR 0101): what every app on Wyndlass's screens shares, Wyndlass's own and an
+ * organization's. Its context from the host, its props with their defaults, drawing from the layout's clock (so seeking
+ * and pausing draw the right moment), saying it is ready once, and its enter and exit presets on that clock.
+ *
+ * Both shapes of the app contract (WP-0100, ADR 0100): a host of Player API 2 defines the bundle's default export under
+ * a tag of its own and hands it the context once, through ATTACH, leaving nothing on the element; an older one reads the
+ * tag the bundle defined (`define`) and sets the context as `element.wyndlass`.
+ *
+ * Outside a host (a unit test, the SDK's preview before it gives one) an app still runs: the time is now, each prop is
+ * its default, data and images are refused as unavailable, and ready() does nothing.
+ */
+import { ATTACH, type AppContext, type AppController, type DataAnswer, type HookOptions, type ImpressionsFeed } from "./contract/app-contract.js";
+export { ATTACH };
+export type { AppContext, AppController, AppElement, AppModule, AppCapability, DataAnswer, HookOptions, ImpressionsFeed, ImpressionsNow, ImpressionEvent, ScreenFacts, TableBinding, TableRule, TimeNow, NotApplied, } from "./contract/app-contract.js";
+export type { AppDefinition } from "./contract/app-definition.js";
+/** The data service's answers, one namespace for each source (data-*.schema.json). */
+export type * as calendar from "./contract/data-calendar.js";
+export type * as news from "./contract/data-news.js";
+export type * as quotes from "./contract/data-quotes.js";
+export type * as series from "./contract/data-series.js";
+export type * as weather from "./contract/data-weather.js";
+export type * as tables from "./contract/data-snapshot.js";
+export { cubicBezier, easingOf, staggerTimes } from "./easing.js";
+/** A default's type, widened: a prop that defaults to "digital" may be any string. */
+type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type Params = Record<string, string | number | boolean>;
+/** An app's context, however the host gave it; none outside a host. */
+export declare function contextOf(app: WyndlassApp): AppContext | undefined;
+/** The data service's answer for a source the definition declares (data-answer.schema.json); refused outside a host. */
+export declare function data<T = unknown>(app: WyndlassApp, source: string, params: Params): Promise<DataAnswer<T>>;
+/** The answer the screen last kept for the same request, however old, at once (WP-0111); none before the first, or here. */
+export declare function kept<T = unknown>(app: WyndlassApp, source: string, params: Params): DataAnswer<T> | undefined;
+/** An image a data answer names, as a blob URL the app can draw; refused outside a host. */
+export declare function image(app: WyndlassApp, path: string): Promise<string>;
+/** A data table's snapshot as the manifest carries it, the bound table's with only the rows the binding chooses; null without one. */
+export declare function snapshot(app: WyndlassApp, table: string): unknown | null;
+/** The app's view of the player's controller (ADR 0050), on screens, as its definition's `capabilities.player` allows. */
+export declare function controllerOf(app: WyndlassApp): AppController | undefined;
+/** The people at the screen (WP-0105), where the definition declares the impressions sensor and the site measures. */
+export declare function impressionsOf(app: WyndlassApp): ImpressionsFeed | undefined;
+export declare abstract class WyndlassApp extends HTMLElement {
+    #private;
+    /** The context as a host older than Player API 2 sets it. Declared only, so nothing is left on a newer host's element. */
+    wyndlass?: AppContext;
+    protected root: ShadowRoot;
+    /** Player API 2: the host hands the context over once, before the element joins the document; a second is ignored. */
+    [ATTACH](context: AppContext): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** A prop, or its default when it is absent or empty. */
+    protected prop<T>(name: string, fallback: T): Widen<T>;
+    /** The font prop, a typography value (layout.schema.json#/$defs/typography, WP-0068 part e), as CSS for the app's box. */
+    protected font(): string;
+    /**
+     * Styles for the app's shadow root, as a constructable stylesheet (adoptedStyleSheets), not a <style>: a page whose
+     * style policy uses nonces still draws it (WP-0124 decision 9). Each call adds a sheet after the others. Call it from
+     * mount(), once the root is there.
+     */
+    protected css(text: string): CSSStyleSheet;
+    /** The layout's clock: now, or the moment it is held at when seeked or paused. */
+    protected now(): number;
+    /** When the layout started, on the same clock. */
+    protected startedAt(): number;
+    protected get timeZone(): string;
+    protected get locale(): string;
+    /** Says the app may be shown; once. Within 5 s of its start, or the screen reports it late. */
+    protected ready(): void;
+    /** Builds the app's shadow DOM, once. */
+    protected abstract mount(): void;
+    /** Draws the moment `epochMs` on the layout's clock. */
+    protected abstract draw(epochMs: number): void;
+    update(epochMs: number): void;
+    enter(o: HookOptions): void;
+    exit(o: HookOptions): void;
+    /** Forgets the enters and exits given so far (the designer gives them again when the clips change). */
+    reset(): void;
+    /** A paged app's items, for a staggered enter or exit (ADR 0071, decision 4); none animates the app as one box. */
+    protected staggered(): HTMLElement[];
+}
+/** A size that fits the app's box: the smaller of a share of its height and a share of its width (--h and --w). */
+export declare function fit(ofHeight: number, ofWidth: number): string;
+/** A typography value as CSS: its face, decoration, letter case, spacing, line height, shadow, and its scale as --s. */
+export declare function typographyCss(value: unknown): string;
+/** The colour props as CSS, with a fallback. */
+export declare function color(v: unknown, fallback: string): string;
+/**
+ * Defines an element once, under its fixed tag, and returns the tag (the bundle's `element` export): the old shape, for
+ * players older than Player API 2, which only Wyndlass's own apps need. A newer host defines the default export under a
+ * tag of its own instead.
+ */
+export declare function define(tag: string, element: CustomElementConstructor): string;
+/** Text safe to put in markup. */
+export declare function escape(s: string): string;