@gratiaos/pad-core 1.0.7 → 1.1.1

package/README.md

@@ -10,6 +10,15 @@ 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.
 
+### 🛰️ Garden Stack naming (infra-facing)
+
+- **Pattern Engine** → underlying model stack (training / inference / retrieval). Use this wording for infra, capabilities, or updates.
+- **Presence Node** → surfaced endpoint humans touch (web UI, CLI, scripts, voice, agents).
+- **Mode** → behavioral / conversational contract for a Presence Node (e.g. `Codex-mode`, `Monday-mode`). Styles, never identities.
+- **Garden Stack** → Pattern Engine + Presence Nodes + Modes in concert.
+
+Translate any “AI” mention to the correct layer so pads, mirrors, and docs stay coherent.
+
 ### 🔩 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:

package/dist/garden-broadcaster.d.ts

@@ -0,0 +1,39 @@
+import { type GardenEnvelope, type GardenEnvelopeMeta, type GardenProtocolType, type GardenPayloadMap, type GardenPulsePayload, type GardenBreathPayload, type GardenWeavePayload, type GardenMomentPayload, type GardenConsentPayload } from './garden-protocol.js';
+export type GardenBroadcasterOrigin = 'local' | 'remote';
+export type GardenBroadcasterListener = (packet: GardenEnvelope, origin: GardenBroadcasterOrigin) => void;
+export type GardenShareGate = <T extends GardenProtocolType>(type: T, payload: GardenPayloadMap[T]) => boolean;
+export type GardenRedactFn = <T extends GardenProtocolType>(type: T, payload: GardenPayloadMap[T]) => GardenPayloadMap[T] | null | undefined;
+export interface GardenBroadcasterOptions {
+    channelName?: string;
+    actor?: string;
+    scene?: string;
+    canShare?: GardenShareGate;
+    gate?: GardenShareGate;
+    redact?: GardenRedactFn;
+}
+export declare class GardenBroadcaster {
+    private readonly channel;
+    private readonly listeners;
+    private readonly detachChannel;
+    private disposed;
+    private gate;
+    private redact?;
+    private actor?;
+    private scene?;
+    constructor(options?: GardenBroadcasterOptions);
+    get hasChannel(): boolean;
+    updateDefaults(meta: GardenEnvelopeMeta): void;
+    setShareGate(gate: GardenShareGate): void;
+    setRedactor(redact?: GardenRedactFn): void;
+    publish<T extends GardenProtocolType>(type: T, payload: GardenPayloadMap[T], meta?: GardenEnvelopeMeta): void;
+    mirrorPulse(payload: GardenPulsePayload, meta?: GardenEnvelopeMeta): void;
+    mirrorBreath(payload: GardenBreathPayload, meta?: GardenEnvelopeMeta): void;
+    mirrorWeave(payload: GardenWeavePayload, meta?: GardenEnvelopeMeta): void;
+    mirrorMoment(payload: GardenMomentPayload, meta?: GardenEnvelopeMeta): void;
+    mirrorConsent(payload: GardenConsentPayload, meta?: GardenEnvelopeMeta): void;
+    onPacket(listener: GardenBroadcasterListener): () => void;
+    on<T extends GardenProtocolType>(type: T, listener: (packet: GardenEnvelope<T>, origin: GardenBroadcasterOrigin) => void): () => void;
+    dispose(): void;
+    private emit;
+}
+export declare function createGardenBroadcaster(options?: GardenBroadcasterOptions): GardenBroadcaster;

package/dist/garden-broadcaster.js

@@ -0,0 +1,142 @@
+import { createGardenEnvelope, parseGardenEnvelope, } from './garden-protocol.js';
+const BroadcastChannelCtor = typeof globalThis !== 'undefined' && typeof globalThis.BroadcastChannel === 'function'
+    ? globalThis.BroadcastChannel
+    : null;
+const defaultGate = () => true;
+export class GardenBroadcaster {
+    constructor(options = {}) {
+        this.listeners = new Set();
+        this.disposed = false;
+        this.gate = options.gate ?? options.canShare ?? defaultGate;
+        this.redact = options.redact;
+        this.actor = options.actor;
+        this.scene = options.scene;
+        if (!BroadcastChannelCtor) {
+            this.channel = null;
+            this.detachChannel = null;
+            return;
+        }
+        this.channel = new BroadcastChannelCtor(options.channelName ?? 'garden');
+        const handler = (event) => {
+            if (this.disposed)
+                return;
+            const packet = parseGardenEnvelope(event?.data);
+            if (!packet)
+                return;
+            this.emit(packet, 'remote');
+        };
+        if (typeof this.channel.addEventListener === 'function' && typeof this.channel.removeEventListener === 'function') {
+            this.channel.addEventListener('message', handler);
+            this.detachChannel = () => {
+                try {
+                    this.channel?.removeEventListener?.('message', handler);
+                }
+                catch {
+                    /* noop */
+                }
+            };
+        }
+        else {
+            this.channel.onmessage = handler;
+            this.detachChannel = () => {
+                if (this.channel && this.channel.onmessage === handler) {
+                    this.channel.onmessage = null;
+                }
+            };
+        }
+    }
+    get hasChannel() {
+        return Boolean(this.channel);
+    }
+    updateDefaults(meta) {
+        this.actor = meta.actor ?? this.actor;
+        this.scene = meta.scene ?? this.scene;
+    }
+    setShareGate(gate) {
+        this.gate = gate ?? defaultGate;
+    }
+    setRedactor(redact) {
+        this.redact = redact;
+    }
+    publish(type, payload, meta = {}) {
+        if (this.disposed)
+            return;
+        if (!this.gate(type, payload))
+            return;
+        const sanitized = this.redact ? this.redact(type, payload) : payload;
+        if (sanitized == null)
+            return;
+        const packet = createGardenEnvelope(type, sanitized, {
+            actor: meta.actor ?? this.actor,
+            scene: meta.scene ?? this.scene,
+            ts: meta.ts,
+        });
+        try {
+            this.channel?.postMessage(packet);
+        }
+        catch {
+            /* ignore broadcast failures */
+        }
+        this.emit(packet, 'local');
+    }
+    mirrorPulse(payload, meta) {
+        this.publish('pulse', payload, meta);
+    }
+    mirrorBreath(payload, meta) {
+        this.publish('breath', payload, meta);
+    }
+    mirrorWeave(payload, meta) {
+        this.publish('weave', payload, meta);
+    }
+    mirrorMoment(payload, meta) {
+        this.publish('moment', payload, meta);
+    }
+    mirrorConsent(payload, meta) {
+        this.publish('consent', payload, meta);
+    }
+    onPacket(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    on(type, listener) {
+        const wrapped = (packet, origin) => {
+            if (packet.type !== type)
+                return;
+            listener(packet, origin);
+        };
+        return this.onPacket(wrapped);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        try {
+            this.detachChannel?.();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            this.channel?.close();
+        }
+        catch {
+            /* ignore */
+        }
+        this.listeners.clear();
+    }
+    emit(packet, origin) {
+        this.listeners.forEach((listener) => {
+            try {
+                listener(packet, origin);
+            }
+            catch {
+                /* swallow listener errors */
+            }
+        });
+    }
+}
+export function createGardenBroadcaster(options) {
+    return new GardenBroadcaster(options);
+}

package/dist/garden-protocol.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Garden Protocol v0 (g1)
+ * -------------------------------------------------------
+ * Small, forward-compatible envelope shared between pads,
+ * rituals, and auxiliary surfaces. Designed to travel across
+ * BroadcastChannel, WebRTC, or any transport that can move JSON.
+ */
+export declare const GARDEN_PROTOCOL_VERSION: "g1";
+export type GardenProtocolVersion = typeof GARDEN_PROTOCOL_VERSION;
+export type GardenProtocolType = 'pulse' | 'breath' | 'weave' | 'moment' | 'consent';
+export type GardenPacketType = GardenProtocolType;
+export interface GardenPulsePayload {
+    tick: number;
+    phase?: string;
+    mood?: string;
+    strength?: number;
+}
+export interface GardenBreathPayload {
+    stage: 'inhale' | 'exhale' | 'hold';
+    cadenceMs?: number;
+    depth?: 'soft' | 'deep' | (string & {});
+    coherence?: number;
+    hue?: number;
+    phase?: 'inhale' | 'exhale' | 'hold';
+}
+export interface GardenWeavePayload {
+    beadId?: string;
+    color?: string;
+    energy?: number;
+    hue?: number;
+    tone?: unknown;
+    meta?: Record<string, unknown>;
+}
+export interface GardenMomentPayload {
+    id: string;
+    state?: 'open' | 'close' | 'interrupted' | 'complete' | (string & {});
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+export interface GardenConsentPayload {
+    scope: 'memory' | 'share' | 'telemetry' | (string & {});
+    granted: boolean;
+    depth?: 'ambient' | 'soft' | 'deep' | (string & {});
+    expiresAt?: number;
+}
+export type GardenPayloadMap = {
+    pulse: GardenPulsePayload;
+    breath: GardenBreathPayload;
+    weave: GardenWeavePayload;
+    moment: GardenMomentPayload;
+    consent: GardenConsentPayload;
+};
+export type GardenEnvelope<T extends GardenProtocolType = GardenProtocolType> = {
+    v: GardenProtocolVersion;
+    type: T;
+    ts: number;
+    actor?: string;
+    scene?: string;
+    payload: GardenPayloadMap[T];
+};
+export type GardenEnvelopeMeta = {
+    actor?: string;
+    scene?: string;
+    ts?: number;
+};
+export declare function createGardenEnvelope<T extends GardenProtocolType>(type: T, payload: GardenPayloadMap[T], meta?: GardenEnvelopeMeta): GardenEnvelope<T>;
+export declare function isGardenProtocolType(type: unknown): type is GardenProtocolType;
+export declare function isGardenEnvelope(value: unknown): value is GardenEnvelope;
+export declare function parseGardenEnvelope(value: unknown): GardenEnvelope | null;
+export declare function encodeGardenEnvelope(env: GardenEnvelope): string;
+export declare function decodeGardenEnvelope(value: string | unknown): GardenEnvelope | null;

package/dist/garden-protocol.js

@@ -0,0 +1,57 @@
+/**
+ * Garden Protocol v0 (g1)
+ * -------------------------------------------------------
+ * Small, forward-compatible envelope shared between pads,
+ * rituals, and auxiliary surfaces. Designed to travel across
+ * BroadcastChannel, WebRTC, or any transport that can move JSON.
+ */
+export const GARDEN_PROTOCOL_VERSION = 'g1';
+export function createGardenEnvelope(type, payload, meta = {}) {
+    return {
+        v: GARDEN_PROTOCOL_VERSION,
+        type,
+        ts: typeof meta.ts === 'number' ? meta.ts : Date.now(),
+        actor: meta.actor,
+        scene: meta.scene,
+        payload,
+    };
+}
+export function isGardenProtocolType(type) {
+    return type === 'pulse' || type === 'breath' || type === 'weave' || type === 'moment' || type === 'consent';
+}
+export function isGardenEnvelope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.v === GARDEN_PROTOCOL_VERSION &&
+        isGardenProtocolType(value.type) &&
+        typeof value.ts === 'number' &&
+        Object.prototype.hasOwnProperty.call(value, 'payload'));
+}
+export function parseGardenEnvelope(value) {
+    if (isGardenEnvelope(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            return isGardenEnvelope(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof value === 'object' && value !== null && 'data' in value) {
+        const maybeData = value.data;
+        if (typeof maybeData === 'string') {
+            return parseGardenEnvelope(maybeData);
+        }
+        return isGardenEnvelope(maybeData) ? maybeData : null;
+    }
+    return null;
+}
+export function encodeGardenEnvelope(env) {
+    return JSON.stringify(env);
+}
+export function decodeGardenEnvelope(value) {
+    return typeof value === 'string' ? parseGardenEnvelope(value) : parseGardenEnvelope(value);
+}

package/dist/index.d.ts

@@ -21,3 +21,5 @@ 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';
+export { GARDEN_PROTOCOL_VERSION, createGardenEnvelope, parseGardenEnvelope, encodeGardenEnvelope, decodeGardenEnvelope, isGardenEnvelope, isGardenProtocolType, type GardenEnvelope, type GardenEnvelopeMeta, type GardenProtocolType, type GardenPacketType, type GardenPayloadMap, type GardenPulsePayload, type GardenBreathPayload, type GardenWeavePayload, type GardenMomentPayload, type GardenConsentPayload, } from './garden-protocol.js';
+export { GardenBroadcaster, createGardenBroadcaster, type GardenBroadcasterListener, type GardenBroadcasterOrigin, type GardenBroadcasterOptions, type GardenShareGate, type GardenRedactFn, } from './garden-broadcaster.js';

package/dist/index.js

@@ -23,3 +23,5 @@ export * from './hooks/usePadMood';
 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';
+export { GARDEN_PROTOCOL_VERSION, createGardenEnvelope, parseGardenEnvelope, encodeGardenEnvelope, decodeGardenEnvelope, isGardenEnvelope, isGardenProtocolType, } from './garden-protocol.js';
+export { GardenBroadcaster, createGardenBroadcaster, } from './garden-broadcaster.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gratiaos/pad-core",
-  "version": "1.0.7",
+  "version": "1.1.1",
   "description": "Shared pad contract, registry, routing, and realtime events for Garden apps.",
   "funding": "https://github.com/sponsors/GratiaOS",
   "type": "module",