@phreshos/core 0.1.0 → 0.1.2

package/dist/value.js

@@ -0,0 +1,118 @@
+/**
+ * Reduces a strict linear expression into `span * relative + pixels`.
+ *
+ * Numbers are absolute values. Percentages and `n/d` fractions are relative
+ * values. Addition and subtraction combine terms; multiplication and division
+ * scale the preceding term by a number. No arbitrary code or CSS is accepted.
+ */
+export function parseRelativeValue(input) {
+    if (typeof input === "number")
+        return Number.isFinite(input) ? { relative: 0, pixels: clean(input) } : null;
+    if (typeof input !== "string" || input.trim().length === 0)
+        return null;
+    return new Reader(input).parse();
+}
+/** Returns whether a value belongs to the linear relative-value grammar. */
+export function isRelativeValue(value) {
+    return parseRelativeValue(value) !== null;
+}
+class Reader {
+    position = 0;
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    parse() {
+        const value = { relative: 0, pixels: 0 };
+        let direction = this.sign();
+        while (this.position < this.source.length) {
+            const term = this.term();
+            if (!term)
+                return null;
+            value.relative += term.relative * direction;
+            value.pixels += term.pixels * direction;
+            if (!finite(value))
+                return null;
+            this.space();
+            if (this.position === this.source.length)
+                return { relative: clean(value.relative), pixels: clean(value.pixels) };
+            const operator = this.source[this.position];
+            if (operator !== "+" && operator !== "-")
+                return null;
+            this.position += 1;
+            direction = (operator === "+" ? 1 : -1) * this.sign();
+        }
+        return null;
+    }
+    term() {
+        const value = this.measurement();
+        if (!value)
+            return null;
+        while (true) {
+            this.space();
+            const operator = this.source[this.position];
+            if (operator !== "*" && operator !== "/")
+                return value;
+            this.position += 1;
+            const scalar = this.scalar();
+            if (scalar === null || operator === "/" && scalar === 0)
+                return null;
+            const factor = operator === "*" ? scalar : 1 / scalar;
+            value.relative *= factor;
+            value.pixels *= factor;
+            if (!finite(value))
+                return null;
+        }
+    }
+    measurement() {
+        this.space();
+        const remainder = this.source.slice(this.position);
+        const fraction = remainder.match(/^(\d+(?:\.\d+)?|\.\d+)\s*\/\s*(\d+(?:\.\d+)?|\.\d+)(?![\d.])/);
+        if (fraction) {
+            const denominator = Number(fraction[2]);
+            if (!denominator)
+                return null;
+            this.position += fraction[0].length;
+            return { relative: Number(fraction[1]) / denominator, pixels: 0 };
+        }
+        const percentage = remainder.match(/^(\d+(?:\.\d+)?|\.\d+)\s*%/);
+        if (percentage) {
+            this.position += percentage[0].length;
+            return { relative: Number(percentage[1]) / 100, pixels: 0 };
+        }
+        const number = this.number();
+        return number === null ? null : { relative: 0, pixels: number };
+    }
+    scalar() {
+        const direction = this.sign();
+        const value = this.number();
+        return value === null ? null : value * direction;
+    }
+    number() {
+        this.space();
+        const number = this.source.slice(this.position).match(/^(\d+(?:\.\d+)?|\.\d+)/)?.[0];
+        if (!number)
+            return null;
+        this.position += number.length;
+        return Number(number);
+    }
+    sign() {
+        this.space();
+        const sign = this.source[this.position];
+        if (sign !== "+" && sign !== "-")
+            return 1;
+        this.position += 1;
+        this.space();
+        return sign === "-" ? -1 : 1;
+    }
+    space() {
+        while (/\s/.test(this.source[this.position] ?? ""))
+            this.position += 1;
+    }
+}
+function finite(value) {
+    return Number.isFinite(value.relative) && Number.isFinite(value.pixels);
+}
+function clean(value) {
+    return Object.is(value, -0) ? 0 : value;
+}

package/dist/wallpaper.d.ts

@@ -0,0 +1,30 @@
+import type { Program } from "./program.js";
+import type { Launch, LaunchClient } from "./launch.js";
+/** The only Process settings configurable for a desktop Program wallpaper. */
+export type WallpaperLaunch = Readonly<{
+    /** Optional meaningful name unique among the Program's live Processes. */
+    name?: string;
+    /** Whether to include the Program's declared Server. */
+    server?: boolean;
+    /** Optional initial page beneath the Client's declared location scope. */
+    client?: Pick<LaunchClient, "location">;
+    /** Immutable text values available to both endpoints of this Process. */
+    options?: Launch["options"];
+}>;
+/** File-backed wallpaper assigned to one system surface. */
+export interface FileWallpaper {
+    /** Selects one file previously created through `host.serve()`. */
+    set(file: string): Promise<void>;
+    /** Removes the customization so the bundled wallpaper is used. */
+    remove(): Promise<void>;
+}
+/** Desktop wallpaper, backed by either a served file or a Program. */
+export interface DesktopWallpaper extends FileWallpaper {
+    /**
+     * Selects a Program as the desktop wallpaper.
+     *
+     * The Program must declare a Client. Its Client is always started and its
+     * Window becomes a protected wallpaper representation.
+     */
+    setProgram(program: Program, launch?: WallpaperLaunch): Promise<void>;
+}

package/dist/window.d.ts

@@ -1,12 +1,44 @@
-import type { Client } from "./client.js";
 import type { Layer, Position, Size } from "./launch.js";
+import type { ScaleLevel } from "./scale.js";
 import type { Subscribable } from "./subscribable.js";
+/** The authoritative runtime layer occupied by a Window. */
+export type WindowLayer = Layer | "wallpaper";
+/** Stable easing accepted by a Window Surface transaction. */
+export type WindowSurfaceEasing = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | readonly [number, number, number, number];
+/** Motion applied by a desktop when one authoritative Surface target replaces another. */
+export type WindowSurfaceTransaction = Readonly<{
+    /** Duration in milliseconds. Omission uses the system duration. */
+    duration?: number;
+    /** Timing curve. Omission uses the system curve. */
+    easing?: WindowSurfaceEasing;
+}>;
+/** Authoritative target settings for one Window's optional host Surface. */
+export type WindowSurfaceSettings = Readonly<{
+    /** Whole-Surface opacity from zero through one. Omission means one. */
+    opacity?: number;
+    /** A Theme-derived level, CSS pixels, or maximum proportional rounding. Omission means zero. */
+    radius?: ScaleLevel | number | "full";
+    /** Optional motion from the currently rendered values to this target. */
+    transaction?: WindowSurfaceTransaction;
+}>;
+/** Optional host-rendered material owned by one authoritative Window. */
+export interface WindowSurface {
+    /** Creates or replaces the authoritative target. Omission creates the default Surface. */
+    set(settings?: WindowSurfaceSettings): Promise<void>;
+    /** Immediately removes the authoritative Surface. */
+    remove(): Promise<void>;
+}
 /** Events emitted when authoritative Window state changes. */
 export type WindowEvents = {
+    /** The authoritative top-left position changed. */
     move: Position;
+    /** The authoritative width or height changed. */
     resize: Size;
+    /** The authoritative minimized state changed. */
     minimize: boolean;
+    /** The authoritative title changed. */
     changeTitle: string;
+    /** Whether this Window became or ceased to be frontmost in its layer. */
     front: boolean;
 };
 /** Current authoritative Window state. */
@@ -21,18 +53,15 @@ export type WindowState = Readonly<{
     minimized: boolean;
     /** Whether the Window is frontmost in its layer. */
     front: boolean;
-    /** Structurally isolated desktop layer containing the Window. */
-    layer: Layer;
+    /** Authoritative desktop layer containing the Window. */
+    layer: WindowLayer;
     /** Current page beneath the declared Client location. */
     location: string;
 }>;
-/** The Window owned by one live Client. */
-export declare class Window<Events extends object = {}> {
-    constructor();
-}
-export interface Window<Events extends object = {}> extends Subscribable<WindowEvents & Events, never> {
-    /** Returns the Client that owns this Window. */
-    client(): Client;
+/** Presentation capability owned by one Client handle. */
+export interface Window extends Subscribable<WindowEvents, never> {
+    /** Authoritative host-rendered material associated with this Window. */
+    readonly surface: WindowSurface;
     /** Returns the current title. */
     title(): Promise<string>;
     /** Returns the current top-left position. */
@@ -43,8 +72,8 @@ export interface Window<Events extends object = {}> extends Subscribable<WindowE
     minimized(): Promise<boolean>;
     /** Returns whether the Window is frontmost in its layer. */
     front(): Promise<boolean>;
-    /** Returns the structurally isolated desktop layer containing the Window. */
-    layer(): Promise<Layer>;
+    /** Returns the authoritative desktop layer containing the Window. */
+    layer(): Promise<WindowLayer>;
     /** Returns the current page rooted beneath the declared Client location. */
     location(): Promise<string>;
     /** Moves the authoritative Window. */

package/dist/window.js

@@ -1,4 +0,0 @@
-/** The Window owned by one live Client. */
-export class Window {
-    constructor() { }
-}

package/package.json

@@ -1,27 +1,53 @@
 {
   "name": "@phreshos/core",
-  "version": "0.1.0",
-  "description": "Shared domain contracts for Program SDKs.",
+  "version": "0.1.2",
+  "description": "Environment-neutral contracts and domain objects for PhreshOS Programs.",
   "type": "module",
+  "sideEffects": false,
   "main": "dist/main.js",
-  "types": "source/main.ts",
+  "types": "dist/main.d.ts",
   "exports": {
     ".": {
-      "types": "./source/main.ts",
+      "types": "./dist/main.d.ts",
       "default": "./dist/main.js"
     }
   },
   "files": [
     "dist",
-    "source",
+    "LICENSE",
     "README.md"
   ],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhreshOS/core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PhreshOS/core/issues"
+  },
+  "homepage": "https://github.com/PhreshOS/core#readme",
+  "keywords": [
+    "phreshos",
+    "sdk",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
   "scripts": {
-    "check": "tsc --noEmit",
-    "build": "tsc --noEmit false --outDir dist --rootDir source",
-    "prepack": "node --run build"
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "node --run check && node --run test && node --run build && node --run verify:package",
+    "prepack": "node --run test && node --run build"
   },
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.1"
   }
 }

package/source/askable.ts

@@ -1,26 +0,0 @@
-import type { Publishable } from "./publishable.js"
-
-/** An immutable Askable view using one caller-selected deadline. */
-export interface TimedAskable {
-  /** Sends one question and waits within the selected deadline. */
-  ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>
-}
-
-/** A publishing target that can also receive a question and return an answer. */
-export interface Askable<Events extends object = {}, Fallback = unknown>
-  extends Publishable<Events, Fallback> {
-  /**
-   * Sends one question payload to this target and waits for its answer.
-   *
-   * The SDK uses a ten-second deadline by default. It sends the question only
-   * after the current Server incarnation becomes ready. The operation rejects
-   * immediately when that Server is absent, and also rejects if the incarnation
-   * stops before readiness or before answering. One SDK deadline covers both
-   * readiness and the answer. The boundary cannot infer whether an answerer
-   * exists, so a ready unanswered question waits for that deadline.
-   */
-  ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>
-
-  /** Returns an immutable view whose `ask()` uses this deadline in milliseconds. */
-  timeout(milliseconds: number): TimedAskable
-}

package/source/channel.ts

@@ -1,28 +0,0 @@
-import type { Endpoint } from "./endpoint.js"
-import type { Captures, Subscribable } from "./subscribable.js"
-
-/** One application value arriving through the current Endpoint's Channel. */
-export type ChannelMessage<Payload = unknown, From = Endpoint> = Readonly<{
-  /** Endpoint that sent the message, or `null` when its identity is outside this boundary. */
-  from: From
-
-  /** Single value supplied by the publisher. */
-  payload: Payload
-}>
-
-/** Applies the sender envelope to every application event accepted here. */
-export type ChannelEvents<Events extends object, From = Endpoint> = {
-  readonly [Event in keyof Events]: ChannelMessage<Events[Event], From>
-}
-
-type ChannelFallback<Events extends object, From> = keyof Events extends never
-  ? ChannelMessage<unknown, From>
-  : never
-
-/** Every application event observable through a Channel. */
-export type ChannelCapture<Events extends object = {}, From = Endpoint> =
-  Captures<ChannelEvents<Events, From>, ChannelFallback<Events, From>>
-
-/** Events explicitly accepted by the current Endpoint. */
-export interface Channel<Events extends object = {}, From = Endpoint>
-  extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>> {}

package/source/client.ts

@@ -1,29 +0,0 @@
-import { Endpoint, type EndpointTraffic } from "./endpoint.js"
-import type { LaunchClient } from "./launch.js"
-import type { Server } from "./server.js"
-import type { Window } from "./window.js"
-
-/** Broad communication originating from one Client. */
-export interface ClientTraffic<
-  Events extends object = {},
-  To = Endpoint,
-  AskTo = Server
-> extends EndpointTraffic<Events, To, AskTo> {}
-
-/** The client Endpoint of a Process. */
-export class Client<Events extends object = {}> extends Endpoint<Events> {
-  public constructor() {
-    super()
-  }
-}
-
-export interface Client<Events extends object = {}> {
-  /** Broad communication originating from this Client. */
-  readonly traffic: ClientTraffic<Events>
-
-  /** Starts a fresh Client and Window using optional Process-local overrides. */
-  start(overrides?: LaunchClient): Promise<void>
-
-  /** Returns the Window owned by this live Client. */
-  window(): Promise<Window>
-}

package/source/config.ts

@@ -1,104 +0,0 @@
-import type { Layer, Position, Size } from "./launch.js"
-
-/** Development settings for a Program's Server. */
-export type ServerDevelopment = Readonly<{
-  /** Command that starts the development Server from the project directory. */
-  startCommand: string
-}>
-
-/** Development settings for a Program's Client. */
-export type ClientDevelopment = Readonly<{
-  /** HTTP(S) URL served by the Client's development server. */
-  url: string
-
-  /** Optional command that starts the Client's development server. */
-  startCommand?: string
-}>
-
-/** Authoring declaration for a Program's Server. */
-export type ServerConfig = Readonly<{
-  /** Production directory containing the Server. */
-  location: string
-
-  /** Whether a default Process starts its Server. Defaults to `true`. */
-  start?: boolean
-
-  /** Optional preparation command run from {@link location} while installing. */
-  installCommand?: string
-
-  /** Command that starts the production Server from {@link location}. */
-  startCommand: string
-
-  /** Settings used only by the development command. */
-  development?: ServerDevelopment
-}>
-
-/** Authoring declaration for a Program's Client and initial Window. */
-export type ClientConfig = Readonly<{
-  /** Production directory containing the Client and its `index.html`. */
-  location: string
-
-  /** Whether a default Process starts its Client. Defaults to `true`. */
-  start?: boolean
-
-  /** Initial Window title. Defaults to the Program name. */
-  title?: string
-
-  /** Initial Window size. */
-  size?: Size
-
-  /** Initial Window position. */
-  position?: Position
-
-  /** Structurally isolated desktop layer containing the Window. */
-  layer?: Layer
-
-  /** Whether the Window initially opens minimized. */
-  minimize?: boolean
-
-  /** Settings used only by the development command. */
-  development?: ClientDevelopment
-}>
-
-type Description = Readonly<{
-  /** Stable public identity written in kebab-case. */
-  identity: string
-
-  /** Human-readable Program name. Defaults to {@link identity}. */
-  name?: string
-
-  /** Program version shown to people and included in packages. */
-  version?: string
-
-  /** Short human-readable explanation of what the Program does. */
-  description?: string
-
-  /** Markdown file that officially introduces the Program's API. */
-  apiDocs?: string
-
-  /** Directory containing the Program's sized icons. */
-  icons?: string
-
-  /** Command run before production start, installation, and packaging. */
-  buildCommand?: string
-}>
-
-/**
- * The authoring description read from `phresh.config.ts`.
- *
- * A Program must declare a Server, a Client, or both.
- */
-export type Config = Description & (
-  | Readonly<{ server: ServerConfig, client?: ClientConfig }>
-  | Readonly<{ server?: ServerConfig, client: ClientConfig }>
-)
-
-/**
- * Defines a Program authoring description with contextual typing.
- *
- * This helper performs no work and returns the supplied description unchanged.
- * The CLI validates and derives it for development, production, or packaging.
- */
-export function defineConfig<const Description extends Config>(config: Description): Description {
-  return config
-}

package/source/endpoint.ts

@@ -1,95 +0,0 @@
-import type { Process } from "./process.js"
-import type { Publishable } from "./publishable.js"
-import type { Server } from "./server.js"
-import type { Captures, Cleanup, Subscribable } from "./subscribable.js"
-
-/** One application value observed in traffic originating from an Endpoint. */
-export type TrafficMessage<Payload = unknown, To = Endpoint> = Readonly<{
-  /** Destination Endpoint, or `null` when its identity is outside this boundary. */
-  to: To
-
-  /** Single value supplied by the publisher. */
-  payload: Payload
-}>
-
-/** Applies destination metadata to every observed ordinary event. */
-export type TrafficEvents<Events extends object, To = Endpoint> = {
-  readonly [Event in keyof Events]: TrafficMessage<Events[Event], To>
-}
-
-type TrafficFallback<Events extends object, To> = keyof Events extends never
-  ? TrafficMessage<unknown, To>
-  : never
-
-/** One question sent by this Endpoint to a Server. */
-export type AskMessage<Payload = unknown, To = Server> = Readonly<{
-  /** Destination Server, or `null` when its identity is outside this boundary. */
-  to: To
-
-  /** Single question value supplied by the asker. */
-  payload: Payload
-}>
-
-/** One observed question sent by this Endpoint. */
-export type AskCapture<Payload = unknown, To = Server> = Readonly<{
-  /** Event addressed by the question. */
-  event: string
-
-  /** Correlation identity shared with the eventual answer. */
-  questionId: string
-
-  /** Question destination and payload. */
-  message: AskMessage<Payload, To>
-}>
-
-/** A callback that observes questions sent by this Endpoint. */
-export type AskObserver<Payload = unknown, To = Server> = (capture: AskCapture<Payload, To>) => unknown
-
-/** Every ordinary publication observable in traffic from one Endpoint. */
-export type TrafficCapture<Events extends object = {}, To = Endpoint> =
-  Captures<TrafficEvents<Events, To>, TrafficFallback<Events, To>>
-
-/** Broad communication originating from one Endpoint, regardless of destination. */
-export interface EndpointTraffic<
-  Events extends object = {},
-  To = Endpoint,
-  AskTo = Server
-> extends Subscribable<TrafficEvents<Events, To>, TrafficFallback<Events, To>> {
-  /** Observes questions originating from this Endpoint. */
-  observeAsks<Payload = unknown>(observer: AskObserver<Payload, AskTo>): Cleanup
-}
-
-/** The shared Process endpoint represented by Server and Client. */
-export class Endpoint<Events extends object = {}> {
-  public constructor() {}
-}
-
-export interface Endpoint<Events extends object = {}>
-  extends Publishable {
-  /** Broad communication originating from this Endpoint. */
-  readonly traffic: EndpointTraffic<Events>
-
-  /** Returns the Process that owns this Endpoint. */
-  process(): Process
-
-  /** Returns whether this Endpoint currently has a live incarnation. */
-  exists(): Promise<boolean>
-
-  /**
-   * Starts a fresh incarnation without waiting for Server readiness.
-   *
-   * Rejects when the Process is gone or inaccessible, the Program did not
-   * declare this endpoint kind, the Endpoint is already starting or live, or
-   * creation fails.
-   */
-  start(): Promise<void>
-
-  /**
-   * Stops the current incarnation and destroys its boundary-owned resources.
-   *
-   * Rejects when the Process is gone or inaccessible, the Endpoint is already
-   * stopping or absent, this is the Process's final live Endpoint, or stopping
-   * fails. Stopping never exits the Process implicitly.
-   */
-  stop(): Promise<void>
-}

package/source/launch.ts

@@ -1,43 +0,0 @@
-/** A pixel count or a relative linear expression. */
-export type Value = number | string
-
-/** A Window's top-left position. */
-export type Position = Readonly<{
-  /** Horizontal position. */
-  x: Value
-
-  /** Vertical position. */
-  y: Value
-}>
-
-/** A Window's width and height. */
-export type Size = Readonly<{
-  /** Window width. */
-  width: Value
-
-  /** Window height. */
-  height: Value
-}>
-
-/** A structurally isolated desktop layer. */
-export type Layer = "window" | "under" | "over"
-
-/** Every structurally isolated desktop layer. */
-export const layers: readonly Layer[] = ["window", "under", "over"]
-
-/** Per-Process overrides used when starting a Client and its Window. */
-export type LaunchClient = Readonly<{
-  size?: Size
-  position?: Position
-  layer?: Layer
-  location?: string
-  minimize?: boolean
-}>
-
-/** Initial endpoint selection and immutable options for one Process. */
-export type Launch = Readonly<{
-  name?: string
-  server?: boolean
-  client?: boolean | LaunchClient
-  options?: Readonly<Record<string, string>>
-}>