@softov/scena 0.1.2

package/dist/types/manifest.d.ts

@@ -0,0 +1,152 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath, ComponentNode } from './component-graph.js';
+import type { ContextValue } from './when.js';
+import type { SurfaceName, MountPolicy } from './mount-surface.js';
+import type { Permissions } from './permissions.js';
+import type { ArgsSchema } from './command.js';
+import type { ComponentCategory, ComponentDefinition, PropsSchema } from './component-registry.js';
+import type { Converter } from './converter-registry.js';
+import type { DataProviderDefinition, ComputedDefinition } from './reactive-store.js';
+export type ManifestComponent = ComponentDefinition;
+export type ManifestConverter = Converter;
+export type ManifestDataProvider = DataProviderDefinition;
+export interface ManifestComputedPath {
+    path: BindingPath;
+    def: ComputedDefinition;
+}
+export interface ManifestCommand {
+    id: string;
+    title: string;
+    category?: string;
+    icon?: string;
+    keywords?: string[];
+    slots?: string[];
+    when?: string;
+    args?: ArgsSchema;
+    dispatch?: 'client' | 'remote' | 'either';
+    run?: string;
+}
+export interface ManifestKeybinding {
+    keys: string;
+    commandId: string;
+    args?: unknown[];
+    when?: string;
+    scope?: {
+        surfaceName?: SurfaceName;
+        viewId?: string;
+    };
+}
+export interface ManifestView {
+    surface: SurfaceName;
+    key: string;
+    when?: string;
+    component: ComponentNode | string;
+    policy?: MountPolicy;
+}
+export interface ManifestShell {
+    id: string;
+    title?: string;
+    component: string;
+}
+export interface Contributes {
+    components?: ManifestComponent[];
+    converters?: ManifestConverter[];
+    dataProviders?: ManifestDataProvider[];
+    computedPaths?: ManifestComputedPath[];
+    commands?: ManifestCommand[];
+    keybindings?: ManifestKeybinding[];
+    contextKeys?: {
+        key: BindingPath;
+        value: ContextValue;
+    }[];
+    views?: ManifestView[];
+    shells?: ManifestShell[];
+}
+export interface ScenaManifestSource {
+    id: string;
+    version?: string;
+    displayName?: string;
+}
+export interface ScenaManifest {
+    source: ScenaManifestSource;
+    requires?: string[];
+    engine?: {
+        scena: string;
+    };
+    permissions?: Permissions;
+    contributes?: Contributes;
+}
+export interface RuntimeManifestComponent {
+    component: string;
+    category?: ComponentCategory;
+    propsSchema?: PropsSchema;
+    fallback?: ComponentNode;
+    renderer: {
+        kind: 'react';
+        module: string;
+    } | {
+        kind: 'template';
+        template: ComponentNode;
+    } | {
+        kind: 'html';
+        module: string;
+    };
+}
+export interface RuntimeManifestCommand {
+    id: string;
+    title: string;
+    category?: string;
+    icon?: string;
+    keywords?: string[];
+    slots?: string[];
+    when?: string;
+    args?: ArgsSchema;
+    dispatch?: 'client' | 'remote' | 'either';
+    run?: string;
+}
+export interface RuntimeManifestJSON {
+    source: ScenaManifestSource;
+    requires?: string[];
+    engine?: {
+        scena: string;
+    };
+    permissions?: Permissions;
+    contributes?: {
+        components?: RuntimeManifestComponent[];
+        converters?: {
+            id: string;
+            module: string;
+        }[];
+        dataProviders?: {
+            namespace: string;
+            module: string;
+            load?: 'lazy' | 'eager';
+            unloadAfter?: string | number;
+        }[];
+        computedPaths?: {
+            path: BindingPath;
+            module: string;
+        }[];
+        commands?: RuntimeManifestCommand[];
+        keybindings?: ManifestKeybinding[];
+        contextKeys?: {
+            key: BindingPath;
+            value: ContextValue;
+        }[];
+        views?: ManifestView[];
+        shells?: {
+            id: string;
+            title?: string;
+            module: string;
+        }[];
+    };
+}
+export interface ManifestLoader {
+    resolve(spec: string, source: ScenaManifestSource): Promise<unknown>;
+}
+export interface ManifestAPI {
+    load(manifest: ScenaManifest, loader: ManifestLoader): Promise<Disposable>;
+    loadRuntime(manifest: RuntimeManifestJSON, loader: ManifestLoader): Promise<Disposable>;
+    unload(sourceId: string): void;
+    listSources(): ScenaManifestSource[];
+}

package/dist/types/manifest.js

@@ -0,0 +1 @@
+export {};

package/dist/types/mount-menu.d.ts

@@ -0,0 +1,8 @@
+import type { Disposable } from './disposable.js';
+import type { PickerAction } from './host.js';
+import type { ResolvedMount } from './mount-surface.js';
+export type MountMenuContributor = (mount: ResolvedMount) => PickerAction[];
+export interface MountMenuRegistry {
+    register(slot: string, contributor: MountMenuContributor): Disposable;
+    collect(slot: string, mount: ResolvedMount): PickerAction[];
+}

package/dist/types/mount-menu.js

@@ -0,0 +1 @@
+export {};

package/dist/types/mount-surface.d.ts

@@ -0,0 +1,87 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentNode, DataBinding } from './component-graph.js';
+import type { WhenClause } from './when.js';
+import type { ResourceColor } from './colors.js';
+import type { Label } from './label.js';
+export type SurfaceName = 'titlebar' | 'activitybar' | 'sidebar:left' | 'sidebar:right' | 'main' | 'panel:bottom' | 'statusbar' | 'overlay' | 'detached';
+export type MountTarget = ComponentNode | DataBinding;
+export type EditTier = 'basic' | 'content' | 'binding' | 'structure' | 'schema';
+export interface MountPolicy {
+    editable?: boolean;
+    editTier?: EditTier;
+    persistent?: boolean;
+    transient?: boolean;
+    customizable?: boolean;
+}
+export interface MountDisplay {
+    title?: Label;
+    icon?: string;
+    color?: ResourceColor;
+    actions?: MountAction[];
+}
+export interface MountAction {
+    command: string;
+    label?: Label;
+    icon?: string;
+    when?: WhenClause;
+}
+export interface MountDeclaration {
+    surface: SurfaceName;
+    key: string;
+    when?: WhenClause;
+    resource: MountTarget;
+    props?: MountDisplay;
+    policy?: MountPolicy;
+    dataContext?: `$/${string}`;
+}
+export interface ResolvedMount {
+    key: string;
+    surface: SurfaceName;
+    component: ComponentNode;
+    props?: MountDisplay;
+    policy: MountPolicy;
+    dataContext?: `$/${string}`;
+    openedAt: number;
+}
+export interface MountHandle {
+    key: string;
+    surface: SurfaceName;
+    close(opts?: {
+        reason?: string;
+    }): void;
+    focus(): void;
+}
+export interface MountSurfaceRegistry {
+    mount(decl: MountDeclaration): Disposable;
+    open(opts: {
+        surface: SurfaceName;
+        key: string;
+        resource: MountTarget;
+        props?: MountDisplay;
+        policy?: MountPolicy;
+        dataContext?: `$/${string}`;
+    }): MountHandle;
+    openResource(kind: string, args?: OpenResourceArgs): MountHandle | null;
+    close(key: string, opts?: {
+        reason?: string;
+    }): void;
+    focus(key: string): void;
+    listAt(surface: SurfaceName): ResolvedMount[];
+    move(opts: {
+        key: string;
+        toSurface: SurfaceName;
+        fromSurface?: SurfaceName;
+    }): void;
+}
+export interface OpenResourceOptions {
+    surface?: SurfaceName;
+    mountKey?: string;
+    title?: Label;
+    dataContext?: `$/${string}`;
+    focus?: boolean;
+}
+export interface OpenResourceArgs {
+    resourceId?: string;
+    options?: OpenResourceOptions;
+    extraProps?: Record<string, unknown>;
+}

package/dist/types/mount-surface.js

@@ -0,0 +1 @@
+export {};

package/dist/types/permissions.d.ts

@@ -0,0 +1,18 @@
+import type { SurfaceName } from './mount-surface.js';
+export type PermissionPath = `$/${string}`;
+export interface Permissions {
+    read?: PermissionPath[];
+    write?: PermissionPath[];
+    commands?: string[];
+    surfaces?: SurfaceName[];
+    registerComponents?: boolean;
+    registerConverters?: boolean;
+    registerLayouts?: boolean;
+}
+export type PermissionKind = 'read' | 'write' | 'command' | 'surface' | 'register';
+export interface PermissionEngine {
+    allows(sourceId: string, kind: PermissionKind, target?: string): boolean;
+    grant(sourceId: string, permissions: Permissions): void;
+    revoke(sourceId: string): void;
+    permissionsFor(sourceId: string): Permissions | undefined;
+}

package/dist/types/permissions.js

@@ -0,0 +1 @@
+export {};

package/dist/types/query.d.ts

@@ -0,0 +1,34 @@
+export type WhereOp = 'eq' | 'ne' | 'contains' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
+export interface WhereClause {
+    field: string;
+    op: WhereOp;
+    value: unknown;
+}
+export interface Query {
+    q?: string;
+    where?: WhereClause[];
+    page: number;
+    pageSize: number;
+    sort?: {
+        field: string;
+        dir: 'asc' | 'desc';
+    };
+}
+export interface ListView {
+    ids: string[];
+    total: number;
+    loading: boolean;
+    error?: string;
+}
+export interface ResourceApi {
+    list: string;
+    one?: (id: string) => string;
+    pagination?: 'offset' | 'page' | false;
+    search?: 'q' | false;
+    filter?: 'where' | false;
+    sort?: boolean;
+    response?: 'array' | {
+        items: string;
+        total: string;
+    };
+}

package/dist/types/query.js

@@ -0,0 +1,7 @@
+// List/query model — shared by the Pagination/Filter components and the
+// app's resource data providers. A list is a query → view window, NOT
+// "load everything": $/<ns>/query drives $/<ns>/view (ids + total). Server
+// capabilities are declared per-resource (ResourceApi); unsupported bits are
+// applied client-side, so flipping a resource to server-paged later is a
+// provider-internal change with no UI impact.
+export {};

package/dist/types/reactive-store.d.ts

@@ -0,0 +1,39 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath } from './component-graph.js';
+export type ScopeName = 'local' | 'page' | 'workspace' | 'global' | 'summary' | 'active' | 'ui' | 'layout' | `plugins.${string}` | (string & {});
+export type ComputedDefinition = {
+    from: BindingPath[];
+    select: string;
+} | {
+    from: BindingPath[];
+    select: (values: Record<string, unknown>) => unknown;
+};
+export interface SocketBridge {
+    on(event: string, fn: (payload: unknown) => void): Disposable;
+    off(event: string, fn: (payload: unknown) => void): void;
+    offAll(events: string[]): void;
+    emit(event: string, payload?: unknown): void;
+}
+export interface DataProviderDefinition {
+    namespace: string;
+    load?: 'lazy' | 'eager';
+    unloadAfter?: string | number;
+    provider: {
+        load(store: ReactiveStore, socket: SocketBridge): Promise<void> | void;
+        unload?(store: ReactiveStore, socket: SocketBridge): Promise<void> | void;
+        loadOne?(id: string): Promise<unknown>;
+    };
+}
+export interface ReactiveStore {
+    get<T = unknown>(path: BindingPath): T | undefined;
+    set(path: BindingPath, value: unknown): void;
+    patch(path: BindingPath, partial: Record<string, unknown>): void;
+    patchMany(entries: Record<string, unknown>): void;
+    delete(path: BindingPath): void;
+    clearNamespace(scope: ScopeName | string): void;
+    subscribe(path: BindingPath, fn: (value: unknown) => void): Disposable;
+    subscriberCount(scope: ScopeName | string): number;
+    computed(path: BindingPath, def: ComputedDefinition): Disposable;
+    registerDataProvider(def: DataProviderDefinition): Disposable;
+    listDataProviders(): DataProviderDefinition[];
+}

package/dist/types/reactive-store.js

@@ -0,0 +1 @@
+export {};

package/dist/types/scena.d.ts

@@ -0,0 +1,53 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath } from './component-graph.js';
+import type { ComponentRegistry } from './component-registry.js';
+import type { ReactiveStore, SocketBridge } from './reactive-store.js';
+import type { BindingResolver } from './binding-resolver.js';
+import type { MountSurfaceRegistry, SurfaceName } from './mount-surface.js';
+import type { MountMenuRegistry } from './mount-menu.js';
+import type { ConverterRegistry } from './converter-registry.js';
+import type { PermissionEngine } from './permissions.js';
+import type { CommandRegistry } from './command.js';
+import type { KeybindingRegistry } from './keybinding.js';
+import type { ShellRegistry } from './shell.js';
+import type { LayoutAPI, LayoutRegistry, LayoutStorage, ScenaLayout } from './layout.js';
+import type { SessionAPI, SessionStorage } from './session.js';
+import type { ManifestAPI } from './manifest.js';
+import type { EventBus } from './events.js';
+import type { WhenEngine, ContextValue } from './when.js';
+import type { ScopeBackendFactory } from './scope-backend.js';
+export interface Scena extends Disposable {
+    components: ComponentRegistry;
+    store: ReactiveStore;
+    bindings: BindingResolver;
+    surfaces: MountSurfaceRegistry;
+    mountMenus: MountMenuRegistry;
+    layouts: LayoutRegistry;
+    converters: ConverterRegistry;
+    permissions: PermissionEngine;
+    commands: CommandRegistry;
+    keybindings: KeybindingRegistry;
+    shells: ShellRegistry;
+    layout: LayoutAPI;
+    session: SessionAPI;
+    manifest: ManifestAPI;
+    events: EventBus;
+    when: WhenEngine;
+    open: MountSurfaceRegistry['open'];
+    openResource: MountSurfaceRegistry['openResource'];
+    execute: CommandRegistry['execute'];
+    setSessionStorage(s: SessionStorage | null): void;
+    setLayoutStorage(s: LayoutStorage | null): void;
+}
+export interface CreateScenaOptions {
+    initialActive?: Record<BindingPath, ContextValue>;
+    sessionStorage?: SessionStorage;
+    layoutStorage?: LayoutStorage;
+    events?: EventBus;
+    defaultSurface?: SurfaceName;
+    initialLayout?: ScenaLayout;
+    initialShellId?: string;
+    backendFactories?: ScopeBackendFactory[];
+    socket?: SocketBridge;
+}
+export type CreateScena = (opts?: CreateScenaOptions) => Scena;

package/dist/types/scena.js

@@ -0,0 +1 @@
+export {};

package/dist/types/scope-backend.d.ts

@@ -0,0 +1,16 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath } from './component-graph.js';
+export interface ScopeBackend {
+    get(segments: string[]): {
+        hasValue: boolean;
+        value: unknown;
+    };
+    set(segments: string[], value: unknown): void;
+    delete(segments: string[]): void;
+    clear(): void;
+    attach?(emit: (path: BindingPath, value: unknown) => void): Disposable;
+}
+export interface ScopeBackendFactory {
+    scope: string;
+    create(): ScopeBackend;
+}

package/dist/types/scope-backend.js

@@ -0,0 +1 @@
+export {};

package/dist/types/session.d.ts

@@ -0,0 +1,39 @@
+import type { ComponentNode, BindingPath } from './component-graph.js';
+import type { Disposable } from './disposable.js';
+import type { SurfaceName, MountHandle } from './mount-surface.js';
+import type { ContextValue } from './when.js';
+export interface SessionMount {
+    key: string;
+    surface: SurfaceName;
+    component: ComponentNode;
+    state: Record<string, unknown>;
+    openedAt: number;
+}
+export interface SurfaceState {
+    visible?: boolean;
+    activeKey?: string;
+    order?: string[];
+}
+export interface SessionSnapshot {
+    version: 1;
+    capturedAt: number;
+    mounts: SessionMount[];
+    surfaces: Partial<Record<SurfaceName, SurfaceState>>;
+    persistedContext?: Record<BindingPath, ContextValue>;
+}
+export interface SessionStorage {
+    load(): Promise<SessionSnapshot | null>;
+    save(snapshot: SessionSnapshot): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface SessionAPI {
+    snapshot(): SessionSnapshot;
+    restore(snapshot: SessionSnapshot): Promise<{
+        restored: MountHandle[];
+        skipped: SessionMount[];
+    }>;
+    save(): Promise<void>;
+    enableAutoPersist(opts?: {
+        debounceMs?: number;
+    }): Disposable;
+}

package/dist/types/session.js

@@ -0,0 +1 @@
+export {};

package/dist/types/shell.d.ts

@@ -0,0 +1,21 @@
+import type { Disposable } from './disposable.js';
+import type { ScenaLayout } from './layout.js';
+import type { SurfaceName } from './mount-surface.js';
+import type { Scena } from './scena.js';
+export interface ShellProps {
+    scena: Scena;
+    layout: ScenaLayout;
+    renderSurface(surface: SurfaceName): unknown;
+}
+export interface ShellDefinition {
+    id: string;
+    title?: string;
+    component: unknown;
+}
+export interface ShellRegistry {
+    register(def: ShellDefinition): Disposable;
+    unregister(id: string): void;
+    list(): ShellDefinition[];
+    setActive(id: string): void;
+    getActive(): ShellDefinition | null;
+}

package/dist/types/shell.js

@@ -0,0 +1 @@
+export {};

package/dist/types/when.d.ts

@@ -0,0 +1,10 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath } from './component-graph.js';
+export type ContextValue = unknown;
+export type ContextSnapshot = Partial<Record<BindingPath, ContextValue>>;
+export type WhenClause = string | ((ctx: ContextSnapshot) => boolean);
+export interface WhenEngine {
+    evaluate(clause: WhenClause, ctx?: ContextSnapshot): boolean;
+    watch(clause: WhenClause, fn: (value: boolean) => void): Disposable;
+    dependencies(clause: WhenClause): BindingPath[];
+}

package/dist/types/when.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/_utils.d.ts

@@ -0,0 +1,8 @@
+import type { CSSProperties } from 'react';
+import type { Label } from '../types/label.js';
+export declare function labelText(label?: Label): string;
+export type StyleJustify = 'start' | 'center' | 'end' | 'spaceAround' | 'spaceBetween' | 'spaceEvenly' | 'stretch' | 'space-around' | 'space-between';
+export type StyleAlign = 'start' | 'center' | 'end' | 'stretch';
+export declare function mapJustify(j?: StyleJustify, def?: CSSProperties['justifyContent']): CSSProperties['justifyContent'];
+export declare function mapAlign(a?: StyleAlign, def?: CSSProperties['alignItems']): CSSProperties['alignItems'];
+export declare function weightStyle(weight?: number): CSSProperties;

package/dist/ui/_utils.js

@@ -0,0 +1,53 @@
+import { resolveLabel } from '../core/label.js';
+import { translate } from '../i18n/registry.js';
+// Resolve a Label (string | { t }) to a plain string for non-reactive contexts.
+// `{ path }` titles are resolved reactively by the layout headers via
+// MountTitle / useMountTitle (which descend + subscribe against the mount's
+// dataContext); this only covers the literal / `{ t }` cases.
+export function labelText(label) {
+    return resolveLabel(label, { get: () => undefined, translate });
+}
+export function mapJustify(j, def) {
+    switch (j) {
+        case 'center':
+            return 'center';
+        case 'end':
+            return 'flex-end';
+        case 'spaceAround':
+        case 'space-around':
+            return 'space-around';
+        case 'spaceBetween':
+        case 'space-between':
+            return 'space-between';
+        case 'spaceEvenly':
+            return 'space-evenly';
+        case 'stretch':
+            return 'stretch';
+        case 'start':
+            return 'flex-start';
+        default:
+            return def ?? 'flex-start';
+    }
+}
+export function mapAlign(a, def) {
+    switch (a) {
+        case 'start':
+            return 'flex-start';
+        case 'center':
+            return 'center';
+        case 'end':
+            return 'flex-end';
+        case 'stretch':
+            return 'stretch';
+        default:
+            return def;
+    }
+}
+// a2ui CatalogComponentCommon.weight → CSS flex-grow with min-* guards so a
+// weighted child can shrink below its intrinsic content. Returns {} when
+// weight is unset so callers can spread unconditionally.
+export function weightStyle(weight) {
+    if (typeof weight !== 'number')
+        return {};
+    return { flex: `${weight}`, minWidth: 0, minHeight: 0 };
+}

package/dist/ui/campus/CampusMappa.d.ts

@@ -0,0 +1,18 @@
+import { type CSSProperties } from 'react';
+import type { CampusMappaNode } from './types.js';
+export interface CampusMappaProps {
+    nodes: CampusMappaNode[];
+    onJumpTo(worldX: number, worldY: number): void;
+    width?: number;
+    height?: number;
+    padding?: number;
+    anchor?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    className?: string;
+    style?: CSSProperties;
+}
+export declare function CampusMappa({ nodes, onJumpTo, width, height, padding, anchor, className, style, }: CampusMappaProps): import("react").JSX.Element | null;