@softov/scena 0.1.2

package/dist/core/path-resolver.js

@@ -0,0 +1,169 @@
+export function parsePath(path) {
+    if (typeof path !== 'string' || path.length === 0) {
+        throw new Error(`Invalid path: empty`);
+    }
+    if (path.startsWith('$/')) {
+        return { absolute: true, segments: parseSegments(path.slice(2)) };
+    }
+    if (path.startsWith('/')) {
+        return { absolute: false, segments: parseSegments(path.slice(1)) };
+    }
+    throw new Error(`Invalid path "${path}": must start with "$/" or "/"`);
+}
+function parseSegments(rest) {
+    if (rest === '')
+        return [];
+    const segs = rest.split('/');
+    const out = new Array(segs.length);
+    for (let i = 0; i < segs.length; i++) {
+        const s = segs[i];
+        if (s === '..') {
+            throw new Error(`Invalid path: ".." segment is forbidden — escape to root with "$/"`);
+        }
+        out[i] = unescapePointer(s);
+    }
+    return out;
+}
+function unescapePointer(seg) {
+    // Order matters: ~1 → / first, then ~0 → ~ (so `~01` → `~1`, not `/`).
+    return seg.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function escapePointer(seg) {
+    return seg.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+export function scopeOf(path) {
+    const parsed = parsePath(path);
+    if (!parsed.absolute) {
+        throw new Error(`Cannot determine scope of relative path "${path}"`);
+    }
+    const first = parsed.segments[0];
+    if (!first)
+        throw new Error(`Path "${path}" has no scope segment`);
+    return first;
+}
+// Joins a relative path against its data context. Returns the canonical
+// absolute path string for store I/O. If `path` is already absolute, returns it.
+export function joinAbsolute(dataContext, path) {
+    const parsed = parsePath(path);
+    if (parsed.absolute)
+        return path;
+    if (!dataContext) {
+        throw new Error(`Relative path "${path}" cannot resolve: no data context active`);
+    }
+    const ctx = parsePath(dataContext);
+    if (!ctx.absolute) {
+        throw new Error(`Data context "${dataContext}" must be absolute ($/-form)`);
+    }
+    return joinSegments([...ctx.segments, ...parsed.segments]);
+}
+export function joinSegments(segments) {
+    if (segments.length === 0)
+        return '$/';
+    return ('$/' + segments.map(escapePointer).join('/'));
+}
+// Returns whether `path` contains a wildcard segment.
+export function hasWildcard(path) {
+    return parsePath(path).segments.includes('*');
+}
+// Interpolates `{{ inner }}` substrings inside a path string. Each inner path
+// is resolved and its value (stringified) replaces the substring. Returns the
+// new raw path string (which still needs parsing / joining).
+//
+// Substitutions resolve through readPath, so the inner can itself be absolute,
+// relative, or a `#/` form. Nesting is limited to 1 level for safety.
+export function interpolatePath(store, dataContext, raw, depth = 0) {
+    if (depth > 1)
+        throw new Error(`interpolatePath: recursion limit (1 level)`);
+    if (!raw.includes('{{'))
+        return raw;
+    return raw.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, inner) => {
+        const v = readPath(store, dataContext, inner, depth + 1);
+        return String(v ?? '');
+    });
+}
+// Reads the value at `path`. Handles `$/` absolute, `/` relative, `#/`
+// indirection, `{{ ... }}` interpolation, and hierarchical descent into
+// stored container values.
+//
+// The store is flat (`Map<string, unknown>`), but a path like
+// `$/scope/list/0/name` may refer to a nested location inside a single
+// stored value (an array, then an object). When the full path isn't keyed,
+// we walk down: longest stored ancestor prefix → traverse remaining
+// segments into its value via property / array-index access.
+//
+// Throws on `*` wildcard paths (subscribe instead) and on `..` segments.
+export function readPath(store, dataContext, path, depth = 0) {
+    if (typeof path !== 'string') {
+        throw new Error(`readPath: expected string path`);
+    }
+    const interpolated = path.includes('{{')
+        ? interpolatePath(store, dataContext, path, depth)
+        : path;
+    if (interpolated.startsWith('#/')) {
+        const refPath = ('$' + interpolated.slice(1));
+        const refValue = store.get(refPath);
+        if (typeof refValue !== 'string') {
+            throw new Error(`#/-path reference at "${path}" did not resolve to a path string (got ${typeof refValue})`);
+        }
+        if (depth > 4)
+            throw new Error(`readPath: indirection limit exceeded`);
+        return readPath(store, dataContext, refValue, depth + 1);
+    }
+    const abs = joinAbsolute(dataContext, interpolated);
+    if (hasWildcard(abs)) {
+        throw new Error(`readPath: wildcard paths are read via subscribe only ("${abs}")`);
+    }
+    const direct = store.get(abs);
+    if (direct !== undefined)
+        return direct;
+    return walkInto(store, abs);
+}
+// Walks down from the longest stored ancestor prefix of `abs`, descending
+// into its value via the remaining segments. Returns undefined when no
+// prefix is stored or traversal hits a non-container.
+function walkInto(store, abs) {
+    const parsed = parsePath(abs);
+    if (!parsed.absolute || parsed.segments.length === 0)
+        return undefined;
+    for (let i = parsed.segments.length - 1; i >= 1; i--) {
+        const prefix = joinSegments(parsed.segments.slice(0, i));
+        const base = store.get(prefix);
+        if (base === undefined)
+            continue;
+        return descend(base, parsed.segments.slice(i));
+    }
+    return undefined;
+}
+function descend(value, segments) {
+    let cur = value;
+    for (const seg of segments) {
+        if (cur === null || cur === undefined)
+            return undefined;
+        if (typeof cur !== 'object')
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = Number(seg);
+            if (!Number.isInteger(idx))
+                return undefined;
+            cur = cur[idx];
+            continue;
+        }
+        cur = cur[seg];
+    }
+    return cur;
+}
+// Writes a value through the resolver. Only plain DataBinding paths are
+// writable — `#/`-form and wildcard paths throw.
+export function writePath(store, dataContext, path, value) {
+    if (path.startsWith('#/')) {
+        throw new Error(`writePath: #/-form paths are read-only ("${path}")`);
+    }
+    const interpolated = path.includes('{{')
+        ? interpolatePath(store, dataContext, path)
+        : path;
+    const abs = joinAbsolute(dataContext, interpolated);
+    if (hasWildcard(abs)) {
+        throw new Error(`writePath: wildcard paths are read-only ("${abs}")`);
+    }
+    store.set(abs, value);
+}

package/dist/core/permissions.d.ts

@@ -0,0 +1,2 @@
+import type { PermissionEngine } from '../types/permissions.js';
+export declare function createPermissionEngine(): PermissionEngine;

package/dist/core/permissions.js

@@ -0,0 +1,50 @@
+export function createPermissionEngine() {
+    const grants = new Map();
+    function matches(pattern, target) {
+        if (pattern === target)
+            return true;
+        if (pattern.endsWith('*')) {
+            const prefix = pattern.slice(0, -1);
+            return target.startsWith(prefix);
+        }
+        return false;
+    }
+    function pathsFor(perms, kind) {
+        switch (kind) {
+            case 'read':
+                return perms.read;
+            case 'write':
+                return perms.write;
+            case 'command':
+                return perms.commands;
+            case 'surface':
+                return perms.surfaces;
+            case 'register':
+                return undefined;
+        }
+    }
+    return {
+        grant(sourceId, perms) {
+            grants.set(sourceId, perms);
+        },
+        revoke(sourceId) {
+            grants.delete(sourceId);
+        },
+        permissionsFor(sourceId) {
+            return grants.get(sourceId);
+        },
+        allows(sourceId, kind, target) {
+            const perms = grants.get(sourceId);
+            if (!perms)
+                return false;
+            if (kind === 'register')
+                return perms.registerComponents !== false;
+            if (!target)
+                return false;
+            const list = pathsFor(perms, kind);
+            if (!list)
+                return false;
+            return list.some((p) => matches(p, target));
+        },
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { BindingPath } from '../types/component-graph.js';
+import type { EventBus } from '../types/events.js';
+import type { ReactiveStore, ScopeName, SocketBridge } from '../types/reactive-store.js';
+import type { ScopeBackendFactory } from '../types/scope-backend.js';
+interface Deps {
+    events: EventBus;
+    socket?: SocketBridge;
+    backendFactories?: ScopeBackendFactory[];
+}
+export interface InternalReactiveStore extends ReactiveStore {
+    _internalKeys(): string[];
+}
+export declare function createReactiveStore(deps: Deps): ReactiveStore;
+export declare function localPath(mountKey: string, suffix: string): BindingPath;
+export declare function rewriteLocal(path: BindingPath, mountKey: string | null): BindingPath;
+export declare function clearMountLocal(store: ReactiveStore, mountKey: string): void;
+export type { ScopeName };