@gratiaos/pad-core 1.0.4 → 1.0.5

package/README.md

@@ -10,6 +10,20 @@ Now extended with **Realtime Presence**, **Scene Events**, and **P2P awareness**
 It’s framework-agnostic, DOM-optional, and designed to let Pads bloom in any app (Playground, M3 UI, future mirrors).  
 The package is side-effect free (`"sideEffects": false`) so bundlers can tree-shake unused helpers.
 
+### 🔩 Signals Interop
+
+Pad Core itself is not opinionated about reactivity; for local observable state (Pad mood, ephemeral counters, lab toggles) prefer the tiny `@gratiaos/signal` package:
+
+```ts
+import { createSignal } from '@gratiaos/signal';
+const mood$ = createSignal<'idle' | 'focused'>('idle');
+const stop = mood$.subscribe((m) => console.log('mood', m));
+mood$.set('focused');
+stop();
+```
+
+Use `@gratiaos/presence-kernel` for shared cross-pad presence/phase signals; use `@gratiaos/signal` when you just need a local synchronous observable.
+
 ---
 
 ## 🌠 Vision

package/dist/catalog.js

@@ -83,12 +83,16 @@ export function buildCatalogFromMany(registries, opts) {
         register: () => {
             throw new Error('immutable view');
         },
+        unregister: () => {
+            throw new Error('immutable view');
+        },
         get: (id) => merged.find((m) => m.id === id),
         list: () => [...merged],
         has: (id) => merged.some((m) => m.id === id),
         clear: () => {
             throw new Error('immutable view');
         },
+        subscribe: () => () => { },
     };
     return buildCatalog(fauxRegistry, opts);
 }

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  * Keep this file small and stable: consumers import from here.
  */
 export type * from './types.js';
-export { createRegistry, sortPads, registerAll, globalRegistry } from './registry.js';
+export { createRegistry, sortPads, registerAll, globalRegistry, getPadManifest, listPadManifests, type PadRegistryChange, } from './registry.js';
 export { DEFAULT_HASH_KEY, getActivePadId, setActivePadId, clearActivePadId, hrefForPad, onPadRouteChange } from './route.js';
 export { padEvents, dispatchPadOpen, dispatchPadClose, dispatchPadBulletinUpdated, onPadOpen, onPadClose, onPadBulletinUpdated } from './events.js';
 export { SCENE_ENTER, SCENE_COMPLETE, dispatchSceneEnter, dispatchSceneComplete, onSceneEnter, onSceneComplete, type SceneEnterDetail, type SceneCompleteDetail, type SceneVia, } from './scene-events.js';
@@ -19,3 +19,5 @@ export { uid, slug } from './id.js';
 export { type CatalogEntry, toCatalogEntry, buildCatalog, mergeRegistries, buildCatalogFromMany, filterCatalog, groupCatalog, pathForPad, findPad, ensurePad, } from './catalog.js';
 export * from './hooks/usePadMood';
 export { setRealtimePort, getRealtimePort, getRealtimeCircleId, onRealtimePortChange } from './realtime/registry.js';
+export { createSignal, type Signal } from './signal.js';
+export { padRegistry$, activePadId$, activeManifest$, scene$, flow$, announceSceneEnter, announceSceneLeave, getActivePadManifest, type FlowSnapshot, } from './state.js';

package/dist/index.js

@@ -10,7 +10,7 @@
  *
  * Keep this file small and stable: consumers import from here.
  */
-export { createRegistry, sortPads, registerAll, globalRegistry } from './registry.js';
+export { createRegistry, sortPads, registerAll, globalRegistry, getPadManifest, listPadManifests, } from './registry.js';
 export { DEFAULT_HASH_KEY, getActivePadId, setActivePadId, clearActivePadId, hrefForPad, onPadRouteChange } from './route.js';
 export { padEvents, dispatchPadOpen, dispatchPadClose, dispatchPadBulletinUpdated, onPadOpen, onPadClose, onPadBulletinUpdated } from './events.js';
 // Scene events (Pad & Scene coordination)
@@ -21,3 +21,5 @@ export { toCatalogEntry, buildCatalog, mergeRegistries, buildCatalogFromMany, fi
 export * from './hooks/usePadMood';
 // Realtime registry (optional integration used by scene-events)
 export { setRealtimePort, getRealtimePort, getRealtimeCircleId, onRealtimePortChange } from './realtime/registry.js';
+export { createSignal } from './signal.js';
+export { padRegistry$, activePadId$, activeManifest$, scene$, flow$, announceSceneEnter, announceSceneLeave, getActivePadManifest, } from './state.js';

package/dist/registry.d.ts

@@ -19,9 +19,23 @@
  * ```
  */
 import type { PadId, PadManifest } from './types.js';
+export type PadRegistryChange = {
+    type: 'pad:register';
+    manifest: PadManifest;
+} | {
+    type: 'pad:update';
+    manifest: PadManifest;
+} | {
+    type: 'pad:unregister';
+    id: PadId;
+} | {
+    type: 'pad:clear';
+};
 export interface PadRegistry {
     /** Insert or replace a pad manifest by id. */
     register(manifest: PadManifest): void;
+    /** Remove a manifest by id (no-op if absent). */
+    unregister(id: PadId): void;
     /** Fetch a manifest by id (undefined if absent). */
     get(id: PadId): PadManifest | undefined;
     /** Return all manifests (unsorted). */
@@ -30,6 +44,8 @@ export interface PadRegistry {
     has(id: PadId): boolean;
     /** Remove all manifests. */
     clear(): void;
+    /** Listen for registry mutations. */
+    subscribe(listener: (change: PadRegistryChange) => void): () => void;
 }
 /**
  * Create a fresh registry with optional initial manifests.
@@ -46,3 +62,7 @@ export declare function registerAll(registry: PadRegistry, manifests: ReadonlyAr
  * Tests can import and call `globalRegistry.clear()` to isolate cases.
  */
 export declare const globalRegistry: PadRegistry;
+/** Helper: fetch a manifest by id from the shared registry. */
+export declare function getPadManifest(id: PadId | string): PadManifest | null;
+/** Helper: list all manifests from the shared registry. */
+export declare function listPadManifests(): PadManifest[];

package/dist/registry.js

@@ -4,11 +4,31 @@
  */
 export function createRegistry(initial) {
     const map = new Map();
+    const listeners = new Set();
+    const notify = (change) => {
+        listeners.forEach((fn) => {
+            try {
+                fn(change);
+            }
+            catch {
+                // ignore listener errors to keep registry resilient
+            }
+        });
+    };
     for (const m of initial ?? [])
         map.set(m.id, m);
     return {
         register(m) {
+            // JS registries run on a single thread; capturing `existed` before `set`
+            // is safe and keeps notify semantics stable for listeners.
+            const existed = map.has(m.id);
             map.set(m.id, m);
+            notify({ type: existed ? 'pad:update' : 'pad:register', manifest: m });
+        },
+        unregister(id) {
+            const existed = map.delete(id);
+            if (existed)
+                notify({ type: 'pad:unregister', id });
         },
         get(id) {
             return map.get(id);
@@ -20,7 +40,17 @@ export function createRegistry(initial) {
             return map.has(id);
         },
         clear() {
-            map.clear();
+            // No-op if already empty. Only emit a 'pad:clear' when at least one manifest was removed.
+            if (map.size > 0) {
+                map.clear();
+                notify({ type: 'pad:clear' });
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
         },
     };
 }
@@ -39,3 +69,11 @@ export function registerAll(registry, manifests) {
  * Tests can import and call `globalRegistry.clear()` to isolate cases.
  */
 export const globalRegistry = createRegistry();
+/** Helper: fetch a manifest by id from the shared registry. */
+export function getPadManifest(id) {
+    return globalRegistry.get(id) ?? null;
+}
+/** Helper: list all manifests from the shared registry. */
+export function listPadManifests() {
+    return globalRegistry.list();
+}

package/dist/signal.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export signal primitive from presence-kernel to avoid duplicate implementations.
+ * Consolidation note: previously this file owned its own `createSignal`. Keeping this shim
+ * preserves import paths (`pad-core/src/signal`) while centralizing behavior in
+ * `@gratiaos/presence-kernel` (which itself delegates to `@gratiaos/signal`).
+ */
+export type { SignalListener, Signal } from '@gratiaos/presence-kernel';
+export { createSignal } from '@gratiaos/presence-kernel';

package/dist/signal.js

@@ -0,0 +1 @@
+export { createSignal } from '@gratiaos/presence-kernel';

package/dist/state.d.ts

@@ -0,0 +1,29 @@
+import type { PadId, PadManifest, SceneId } from './types.js';
+import { type Signal } from './signal.js';
+import { type Phase } from '@gratiaos/presence-kernel';
+/**
+ * Phase coupling note:
+ * pad-core consumes the Presence Kernel's `Phase` union directly so pad scene logic
+ * (e.g. flow snapshots, focus handoff + announcements) stays aligned with global
+ * presence semantics. If either package evolves its phase states, update *both*.
+ *
+ * Rationale: avoiding a second alias layer prevents silent divergence ("archive" vs
+ * "archived" etc.). If pad-core ever needs extra pad-only phases, extend here via:
+ *   export type PadPhase = Phase | 'pad-extra';
+ * and adjust downstream snapshots & UI affordances accordingly.
+ */
+export type PadPhase = Phase;
+export declare const padRegistry$: Signal<PadManifest[]>;
+export declare const activePadId$: Signal<PadId | null>;
+export declare const activeManifest$: Signal<PadManifest | null>;
+export declare const scene$: Signal<SceneId | null>;
+export type FlowSnapshot = {
+    pad: PadManifest | null;
+    scene: SceneId | null;
+    phase: Phase;
+    t: number;
+};
+export declare const flow$: Signal<FlowSnapshot>;
+export declare function getActivePadManifest(): PadManifest | null;
+export declare function announceSceneEnter(sceneId: SceneId | null): void;
+export declare function announceSceneLeave(sceneId?: SceneId | null): void;

package/dist/state.js

@@ -0,0 +1,73 @@
+import { createSignal } from './signal.js';
+import { getActivePadId, onPadRouteChange } from './route.js';
+import { getPadManifest, listPadManifests, globalRegistry } from './registry.js';
+import { onSceneEnter } from './scene-events.js';
+import { onPadClose } from './events.js';
+import { phase$, pulse$ } from '@gratiaos/presence-kernel';
+export const padRegistry$ = createSignal(listPadManifests());
+// Global registry lives for the lifetime of the app/test process, so we keep this
+// subscription active; tests rely on globalRegistry.clear() to reset state.
+globalRegistry.subscribe(() => {
+    padRegistry$.set(listPadManifests());
+});
+export const activePadId$ = createSignal(getActivePadId());
+onPadRouteChange((id) => {
+    activePadId$.set(id);
+});
+export const activeManifest$ = createSignal(activePadId$.value ? getPadManifest(activePadId$.value) : null);
+activePadId$.subscribe((id) => {
+    activeManifest$.set(id ? getPadManifest(id) : null);
+});
+padRegistry$.subscribe(() => {
+    const id = activePadId$.value;
+    activeManifest$.set(id ? getPadManifest(id) : null);
+});
+export const scene$ = createSignal(null);
+onSceneEnter((event) => {
+    const detail = event.detail;
+    if (!detail)
+        return;
+    scene$.set(detail.sceneId ?? null);
+});
+onPadClose((detail) => {
+    if (!detail || !detail.id || detail.id === activePadId$.value) {
+        scene$.set(null);
+    }
+});
+activePadId$.subscribe(() => {
+    scene$.set(null);
+});
+const flow$Signal = createSignal({
+    pad: activeManifest$.value,
+    scene: scene$.value,
+    phase: phase$.value,
+    t: pulse$.value,
+});
+const flowEquals = (a, b) => a.pad === b.pad && a.scene === b.scene && a.phase === b.phase && a.t === b.t;
+const refreshFlow = () => {
+    const next = {
+        pad: activeManifest$.value,
+        scene: scene$.value,
+        phase: phase$.value,
+        t: pulse$.value,
+    };
+    if (flowEquals(flow$Signal.value, next))
+        return;
+    flow$Signal.set(next);
+};
+activeManifest$.subscribe(refreshFlow);
+scene$.subscribe(refreshFlow);
+phase$.subscribe(refreshFlow);
+pulse$.subscribe(refreshFlow);
+export const flow$ = flow$Signal;
+export function getActivePadManifest() {
+    return activeManifest$.value;
+}
+export function announceSceneEnter(sceneId) {
+    scene$.set(sceneId ?? null);
+}
+export function announceSceneLeave(sceneId) {
+    if (!sceneId || scene$.value === sceneId) {
+        scene$.set(null);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gratiaos/pad-core",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Shared pad contract, registry, routing, and realtime events for Garden apps.",
   "funding": "https://github.com/sponsors/GratiaOS",
   "type": "module",
@@ -10,6 +10,9 @@
     "registry": "https://registry.npmjs.org/",
     "provenance": true
   },
+  "dependencies": {
+    "@gratiaos/presence-kernel": "workspace:*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/GratiaOS/garden-core.git",