@gratiaos/pad-core 1.0.0

package/dist/scene-events.js

@@ -0,0 +1,113 @@
+import { getRealtimePort, getRealtimeCircleId, onRealtimePortChange } from './realtime/registry.js';
+import { TOPIC_SCENES } from './realtime/port.js';
+/**
+ * Scene Events (Pad Core)
+ * -------------------------------------------------------
+ * Typed CustomEvent helpers for entering and completing Scenes.
+ * Mirrors the pad events API shape (dispatch/on/... with unsubscribe).
+ */
+export const SCENE_ENTER = 'scene:enter';
+export const SCENE_COMPLETE = 'scene:complete';
+function getTarget(target) {
+    // Default to window in the browser; otherwise fallback to a lightweight target.
+    if (target)
+        return target;
+    if (typeof window !== 'undefined' && window)
+        return window;
+    // Node/SSR fallback
+    return new EventTarget();
+}
+/**
+ * Dispatchers
+ * -------------------------------------------------------
+ */
+export function dispatchSceneEnter(detail, target, options) {
+    const t = getTarget(target);
+    const payload = { timestamp: Date.now(), ...detail };
+    const evt = new CustomEvent(SCENE_ENTER, { detail: payload, bubbles: true });
+    t.dispatchEvent(evt);
+    if (options?.skipRealtime)
+        return;
+    try {
+        const rt = getRealtimePort();
+        const circleId = getRealtimeCircleId();
+        if (rt && circleId && rt.status() === 'connected') {
+            rt.publish(TOPIC_SCENES, { kind: 'enter', detail: payload });
+        }
+    }
+    catch { }
+}
+export function dispatchSceneComplete(detail, target, options) {
+    const t = getTarget(target);
+    const payload = { timestamp: Date.now(), ...detail };
+    const evt = new CustomEvent(SCENE_COMPLETE, { detail: payload, bubbles: true });
+    t.dispatchEvent(evt);
+    if (options?.skipRealtime)
+        return;
+    try {
+        const rt = getRealtimePort();
+        const circleId = getRealtimeCircleId();
+        if (rt && circleId && rt.status() === 'connected') {
+            rt.publish(TOPIC_SCENES, { kind: 'complete', detail: payload });
+        }
+    }
+    catch { }
+}
+/**
+ * Listeners
+ * -------------------------------------------------------
+ * Returns an unsubscribe function for convenience.
+ */
+export function onSceneEnter(handler, target) {
+    const t = getTarget(target);
+    t.addEventListener(SCENE_ENTER, handler);
+    return () => t.removeEventListener(SCENE_ENTER, handler);
+}
+export function onSceneComplete(handler, target) {
+    const t = getTarget(target);
+    t.addEventListener(SCENE_COMPLETE, handler);
+    return () => t.removeEventListener(SCENE_COMPLETE, handler);
+}
+/**
+ * Realtime Bridge
+ * -------------------------------------------------------
+ * Listens for active RealtimePort changes from the registry and mirrors
+ * scene:enter / scene:complete messages between peers. Incoming messages
+ * are re-dispatched locally via DOM CustomEvents so all consumers (pads,
+ * monitors, tools) receive them as if they originated locally.
+ */
+let teardownRealtimeScenes = null;
+onRealtimePortChange((port) => {
+    if (teardownRealtimeScenes) {
+        try {
+            teardownRealtimeScenes();
+        }
+        catch { }
+        teardownRealtimeScenes = null;
+    }
+    if (!port)
+        return;
+    if (globalThis?.process?.env?.NODE_ENV !== 'production') {
+        // eslint-disable-next-line no-console
+        console.debug('[pad-core] realtime scenes bridge active');
+    }
+    try {
+        const off = port.subscribe(TOPIC_SCENES, (msg) => {
+            if (!msg || typeof msg !== 'object')
+                return;
+            if (msg.kind === 'enter') {
+                dispatchSceneEnter(msg.detail, null, { skipRealtime: true });
+            }
+            else if (msg.kind === 'complete') {
+                dispatchSceneComplete(msg.detail, null, { skipRealtime: true });
+            }
+        });
+        teardownRealtimeScenes = () => {
+            try {
+                off();
+            }
+            catch { }
+        };
+    }
+    catch { }
+});

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @packageDocumentation
+ * Garden Pads — shared contracts for pads across apps (Playground, M3 UI, etc).
+ *
+ * This file contains only **types and constants**. No DOM or framework code.
+ * - Pad identity and metadata (PadManifest)
+ * - Visual tone and mood vocabulary
+ * - Lightweight pad signal contract (for local bus / adapters)
+ * - Route preferences (hash/path/query) without assuming a router
+ * - Optional CustomEvent detail shapes used by the event helpers
+ */
+/** Stable identifier for a pad (kebab-case recommended). */
+export type PadId = string;
+/** Chrome/semantic tone a pad prefers for its header and accents. */
+export type PadTone = 'accent' | 'positive' | 'warning' | 'danger' | 'neutral';
+/** Stable identifier for a scene within a pad (kebab-case recommended). */
+export type PadSceneId = string;
+/** Alias for clarity in scene-related modules. */
+export type SceneId = PadSceneId;
+/** A pad's transient “mood” (used for micro-animations / ambience). */
+export type PadMood = 'soft' | 'focused' | 'celebratory';
+/** Optional theme nudge a pad can suggest to its host shell. */
+export interface PadTheme {
+    /** CSS color token or hex (host decides how to interpret). */
+    accent?: string;
+    /** Background/surface token or color. */
+    surface?: string;
+}
+/**
+ * Lightweight intra-pad signals (kept framework-agnostic).
+ * Adapters can map these to DOM CustomEvents, context, Rx, etc.
+ */
+export type PadSignal = {
+    type: 'PAD.MOOD.SET';
+    mood: PadMood;
+} | {
+    type: 'PAD.THEME.SET';
+    accent?: string;
+    surface?: string;
+} | {
+    type: 'PAD.EVENT.CAPTURED';
+    payload: {
+        noteId: string;
+    };
+};
+/** Listener signature for the lightweight pad signal bus. */
+export type PadListener = (msg: PadSignal) => void;
+/** How a pad prefers to be addressed in the URL. */
+export type PadRouteMode = 'hash' | 'path' | 'query' | 'auto';
+/** Default route mode for helpers that auto-detect environment. */
+export declare const DEFAULT_ROUTE_MODE: PadRouteMode;
+/** Default query key used when routing via ?pad=<id>. */
+export declare const DEFAULT_QUERY_KEY: "pad";
+/** Preferred addressing for a pad; hosts can honor any subset. */
+export interface PadRouteOptions {
+    /**
+     * Preferred routing mode.
+     * - 'hash': use `#pad=town` (SPAs without server routing)
+     * - 'query': use `?pad=town` (works for SSR/CDN where hash is undesirable)
+     * - 'path': use `/pads/town` (requires host path routing)
+     * - 'auto': helper decides based on environment/capabilities
+     * Defaults to 'auto'.
+     */
+    mode?: PadRouteMode;
+    /**
+     * Hash parameter name used in URLs, e.g. `#pad=town`.
+     * Defaults to `"pad"`; hosts may override.
+     */
+    hashKey?: string;
+    /**
+     * Query parameter used when `mode: 'query'` or for 'auto' fallback, e.g. `?pad=town`.
+     * Defaults to `"pad"`.
+     */
+    queryKey?: string;
+    /**
+     * Preferred absolute path or leaf segment, e.g. `"/pads/town"` or `"town"`.
+     * Hosts may ignore this in favor of hash/query-only routing.
+     */
+    path?: string;
+    /**
+     * Optional path base (e.g., `"/pads"` or `"/app/pads"`). If provided with a
+     * relative `path` like `"town"`, helpers can compose `"/pads/town"`.
+     */
+    pathPrefix?: string;
+}
+/**
+ * Public manifest for a pad. Hosts (shelves, launchers, routers)
+ * read this structure to list, filter, and open pads.
+ */
+export interface PadManifest<Meta extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique id (e.g., "town", "value-bridge", "firegate"). */
+    id: PadId;
+    /** Human title shown in shelves and headers. */
+    title: string;
+    /** Emoji or icon name (host picks renderer). */
+    icon?: string;
+    /** Preferred chrome tone. */
+    tone?: PadTone;
+    /** Search keywords / aliases for launchers. */
+    keywords?: string[];
+    /** One-line whisper/teaser shown on tiles. */
+    whisper?: string;
+    /** Routing hints. */
+    route?: PadRouteOptions;
+    /** Free-form metadata for host-specific extensions. */
+    meta?: Meta;
+    /** Optional loose tags for filters. */
+    tags?: string[];
+    /** Minimal scene manifest list (IDs only; UI pads can enrich). */
+    scenes?: Array<{
+        id: PadSceneId;
+        title?: string;
+    }>;
+    /** Default scene to show when opened (if scenes exist). */
+    defaultSceneId?: PadSceneId;
+}
+/** Default hash key used by route helpers. */
+export declare const DEFAULT_HASH_KEY: "pad";
+export interface PadOpenDetail {
+    id: PadId;
+    /** UX source hint (telemetry / affordance tweaking). */
+    via?: 'tile' | 'link' | 'hotkey' | string;
+}
+export interface PadCloseDetail {
+    /** If omitted, host may close the currently active pad. */
+    id?: PadId;
+    reason?: 'esc' | 'route' | 'programmatic' | string;
+}
+export interface PadBulletinUpdatedDetail {
+    /** Which pad/topic emitted the bulletin update (if known). */
+    padId?: PadId;
+    topic?: string;
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * Garden Pads — shared contracts for pads across apps (Playground, M3 UI, etc).
+ *
+ * This file contains only **types and constants**. No DOM or framework code.
+ * - Pad identity and metadata (PadManifest)
+ * - Visual tone and mood vocabulary
+ * - Lightweight pad signal contract (for local bus / adapters)
+ * - Route preferences (hash/path/query) without assuming a router
+ * - Optional CustomEvent detail shapes used by the event helpers
+ */
+/** Default route mode for helpers that auto-detect environment. */
+export const DEFAULT_ROUTE_MODE = 'auto';
+/** Default query key used when routing via ?pad=<id>. */
+export const DEFAULT_QUERY_KEY = 'pad';
+/** Default hash key used by route helpers. */
+export const DEFAULT_HASH_KEY = 'pad';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@gratiaos/pad-core",
+  "version": "1.0.0",
+  "description": "Shared pad contract, registry, routing, and events for Garden pads.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./realtime": {
+      "types": "./dist/realtime/index.d.ts",
+      "import": "./dist/realtime/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.13",
+    "react": "^19.1.1",
+    "typescript": "^5.9.3",
+    "rimraf": "^6.0.1"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf dist"
+  }
+}