@ziioapp/os-features 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ziioai
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @ziioapp/os-features
+
+浏览器文件工具与 ZiioApp OPFS 目录协议。当前包含文本编码识别、对象 URL 生命周期辅助、OPFS 路径与读写操作，以及 ZiioApp 应用目录布局。
+
+```ts
+import { decodeTextFile } from "@ziioapp/os-features";
+import {
+  ensureZiioOpfsLayout,
+  getZiioOpfsAppPaths,
+  readOpfsTextFile,
+} from "@ziioapp/os-features/opfs";
+
+await ensureZiioOpfsLayout({ appIds: ["my-app"] });
+const paths = getZiioOpfsAppPaths("my-app");
+const text = await readOpfsTextFile(`${paths.appData}/notes.txt`);
+```
+
+OPFS 操作需要支持 `navigator.storage.getDirectory()` 的浏览器环境；不提供 Node.js 文件系统或 Electron 主进程实现。OPFS 数据按浏览器 origin／存储分区隔离，安装同一包不会使不同应用自动共享文件。
+
+`/.ziio`、`/users`、`/apps` 等路径及 `ziioOpfsLayoutVersion` 是持久化协议的一部分，后续修改须考虑已有数据迁移。开发时可使用根入口和 `/files/*`、`/opfs`、`/opfs/*` 子路径；发布产物提供对应的 JavaScript 与类型声明。

package/dist/files/object-url.d.ts

@@ -0,0 +1,17 @@
+export interface ObjectUrlFileEntry {
+    id: string;
+    idx: number;
+    name: string;
+    size: number;
+    lastModified: number;
+    type: string;
+    file: File;
+    url: string;
+}
+export interface CreateObjectUrlFileEntriesOptions {
+    startIndex?: number;
+}
+export declare function createObjectUrlFileEntries(files: File[], options?: CreateObjectUrlFileEntriesOptions): ObjectUrlFileEntry[];
+export declare function revokeObjectUrls(items: Iterable<{
+    url: string;
+} | string>): void;

package/dist/files/object-url.js

@@ -0,0 +1,21 @@
+export function createObjectUrlFileEntries(files, options = {}) {
+    const startIndex = options.startIndex ?? 0;
+    return files.map((file, index) => {
+        const idx = startIndex + index;
+        return {
+            id: `${file.name}:${file.lastModified}:${idx}`,
+            idx,
+            name: file.name,
+            size: file.size,
+            lastModified: file.lastModified,
+            type: file.type,
+            file,
+            url: URL.createObjectURL(file),
+        };
+    });
+}
+export function revokeObjectUrls(items) {
+    for (const item of items) {
+        URL.revokeObjectURL(typeof item === "string" ? item : item.url);
+    }
+}

package/dist/files/text-file.d.ts

@@ -0,0 +1,27 @@
+export { detect } from "jschardet";
+export interface TextEncodingOptions {
+    sampleSize?: number;
+    defaultEncoding?: string;
+    utf8Confidence?: number;
+}
+export interface TextEncodingDetection {
+    encoding: string;
+    confidence: number;
+    rawEncoding?: string;
+}
+export interface DecodedTextFile {
+    id: string;
+    name: string;
+    size: number;
+    lastModified: number;
+    bytes: Uint8Array;
+    text: string;
+    encoding: string;
+    confidence: number;
+    detectedEncoding: string;
+    rawEncoding?: string;
+}
+export declare function readFileBytes(file: File): Promise<Uint8Array>;
+export declare function detectTextEncoding(bytes: Uint8Array, options?: TextEncodingOptions): TextEncodingDetection;
+export declare function decodeText(bytes: Uint8Array, encoding: string): string;
+export declare function decodeTextFile(file: File, options?: TextEncodingOptions): Promise<DecodedTextFile>;

package/dist/files/text-file.js

@@ -0,0 +1,58 @@
+import { detect as detectCharset } from "jschardet";
+export { detect } from "jschardet";
+const defaultSampleSize = 256 * 1024;
+export async function readFileBytes(file) {
+    return new Uint8Array(await file.arrayBuffer());
+}
+export function detectTextEncoding(bytes, options = {}) {
+    const sampleSize = options.sampleSize ?? defaultSampleSize;
+    const sample = binaryString(bytes.slice(0, Math.min(bytes.length, sampleSize)));
+    const detected = detectCharset(sample);
+    const encoding = normalizeEncoding(detected.encoding, detected.confidence, options);
+    return {
+        encoding,
+        confidence: detected.confidence ?? 0,
+        rawEncoding: detected.encoding,
+    };
+}
+export function decodeText(bytes, encoding) {
+    try {
+        return new TextDecoder(encoding).decode(bytes);
+    }
+    catch {
+        return new TextDecoder("utf-8").decode(bytes);
+    }
+}
+export async function decodeTextFile(file, options = {}) {
+    const bytes = await readFileBytes(file);
+    const detection = detectTextEncoding(bytes, options);
+    return {
+        id: `${file.name}:${file.size}:${file.lastModified}`,
+        name: file.name,
+        size: file.size,
+        lastModified: file.lastModified,
+        bytes,
+        text: decodeText(bytes, detection.encoding),
+        encoding: detection.encoding,
+        confidence: detection.confidence,
+        detectedEncoding: detection.encoding,
+        rawEncoding: detection.rawEncoding,
+    };
+}
+function normalizeEncoding(encoding, confidence = 0, options = {}) {
+    const value = (encoding ?? "").toLowerCase();
+    const utf8Confidence = options.utf8Confidence ?? 0.6;
+    if (value.includes("utf") && confidence >= utf8Confidence)
+        return "utf-8";
+    if (value.includes("gb18030"))
+        return "gb18030";
+    if (value.includes("gb") || value.includes("big5"))
+        return value;
+    return options.defaultEncoding ?? "gbk";
+}
+function binaryString(bytes) {
+    let output = "";
+    for (const byte of bytes)
+        output += String.fromCharCode(byte);
+    return output;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { CreateObjectUrlFileEntriesOptions, ObjectUrlFileEntry, } from "./files/object-url.js";
+export { createObjectUrlFileEntries, revokeObjectUrls, } from "./files/object-url.js";
+export type { DecodedTextFile, TextEncodingDetection, TextEncodingOptions, } from "./files/text-file.js";
+export { decodeText, decodeTextFile, detect, detectTextEncoding, readFileBytes, } from "./files/text-file.js";
+export type { EnsureZiioOpfsLayoutOptions, EnsureZiioOpfsLayoutResult, OpfsWriteOptions, OpfsWriteResult, OpfsWriteStatus, ZiioOpfsAppPaths, ZiioOpfsFsRegistry, ZiioOpfsSharedKind, ZiioOpfsUserPaths, } from "./opfs/index.js";
+export { assertZiioOpfsName, defaultZiioOpfsUserId, ensureOpfsDirectories, ensureOpfsDirectory, ensureZiioOpfsLayout, getOpfsDirectoryHandle, getOpfsRootDirectory, getZiioOpfsAppDirs, getZiioOpfsAppPaths, getZiioOpfsBaseDirs, getZiioOpfsUserPaths, joinOpfsPath, joinRelativeOpfsPath, normalizeOpfsPath, normalizeRelativeOpfsPath, opfsBasename, opfsDirectoryExists, opfsDirname, opfsFileExists, readOpfsFile, readOpfsJsonFile, readOpfsTextFile, splitOpfsPath, stripOpfsPrefix, writeOpfsFile, writeOpfsJsonFile, writeOpfsTextFile, ziioOpfsLayoutVersion, ziioOpfsSharedKinds, ziioOpfsSystemPaths, } from "./opfs/index.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createObjectUrlFileEntries, revokeObjectUrls, } from "./files/object-url.js";
+export { decodeText, decodeTextFile, detect, detectTextEncoding, readFileBytes, } from "./files/text-file.js";
+export { assertZiioOpfsName, defaultZiioOpfsUserId, ensureOpfsDirectories, ensureOpfsDirectory, ensureZiioOpfsLayout, getOpfsDirectoryHandle, getOpfsRootDirectory, getZiioOpfsAppDirs, getZiioOpfsAppPaths, getZiioOpfsBaseDirs, getZiioOpfsUserPaths, joinOpfsPath, joinRelativeOpfsPath, normalizeOpfsPath, normalizeRelativeOpfsPath, opfsBasename, opfsDirectoryExists, opfsDirname, opfsFileExists, readOpfsFile, readOpfsJsonFile, readOpfsTextFile, splitOpfsPath, stripOpfsPrefix, writeOpfsFile, writeOpfsJsonFile, writeOpfsTextFile, ziioOpfsLayoutVersion, ziioOpfsSharedKinds, ziioOpfsSystemPaths, } from "./opfs/index.js";

package/dist/opfs/index.d.ts

@@ -0,0 +1,4 @@
+export { appendOpfsFile, appendOpfsTextFile, ensureOpfsDirectories, ensureOpfsDirectory, getOpfsDirectoryHandle, getOpfsRootDirectory, listOpfsDirectory, type OpfsEntryInfo, type OpfsRemoveOptions, type OpfsWriteOptions, type OpfsWriteResult, type OpfsWriteStatus, opfsDirectoryExists, opfsFileExists, readOpfsFile, readOpfsJsonFile, readOpfsTextFile, readOpfsTextLines, removeOpfsEntry, writeOpfsFile, writeOpfsJsonFile, writeOpfsTextFile, } from "./io.js";
+export { assertZiioOpfsName, defaultZiioOpfsUserId, getZiioOpfsAppDirs, getZiioOpfsAppPaths, getZiioOpfsBaseDirs, getZiioOpfsUserPaths, type ZiioOpfsAppPaths, type ZiioOpfsSharedKind, type ZiioOpfsUserPaths, ziioOpfsLayoutVersion, ziioOpfsSharedKinds, ziioOpfsSystemPaths, } from "./layout.js";
+export { joinOpfsPath, joinRelativeOpfsPath, normalizeOpfsPath, normalizeRelativeOpfsPath, opfsBasename, opfsDirname, splitOpfsPath, stripOpfsPrefix, } from "./path.js";
+export { type EnsureZiioOpfsLayoutOptions, type EnsureZiioOpfsLayoutResult, ensureZiioOpfsLayout, type ZiioOpfsFsRegistry, } from "./volume.js";

package/dist/opfs/index.js

@@ -0,0 +1,4 @@
+export { appendOpfsFile, appendOpfsTextFile, ensureOpfsDirectories, ensureOpfsDirectory, getOpfsDirectoryHandle, getOpfsRootDirectory, listOpfsDirectory, opfsDirectoryExists, opfsFileExists, readOpfsFile, readOpfsJsonFile, readOpfsTextFile, readOpfsTextLines, removeOpfsEntry, writeOpfsFile, writeOpfsJsonFile, writeOpfsTextFile, } from "./io.js";
+export { assertZiioOpfsName, defaultZiioOpfsUserId, getZiioOpfsAppDirs, getZiioOpfsAppPaths, getZiioOpfsBaseDirs, getZiioOpfsUserPaths, ziioOpfsLayoutVersion, ziioOpfsSharedKinds, ziioOpfsSystemPaths, } from "./layout.js";
+export { joinOpfsPath, joinRelativeOpfsPath, normalizeOpfsPath, normalizeRelativeOpfsPath, opfsBasename, opfsDirname, splitOpfsPath, stripOpfsPrefix, } from "./path.js";
+export { ensureZiioOpfsLayout, } from "./volume.js";

package/dist/opfs/io.d.ts

@@ -0,0 +1,42 @@
+export interface OpfsWriteOptions {
+    createParents?: boolean;
+    overwrite?: boolean;
+}
+export interface OpfsEntryInfo {
+    kind: "directory" | "file";
+    lastModified: number;
+    name: string;
+    path: string;
+    size: number;
+    type: string;
+}
+export interface OpfsRemoveOptions {
+    recursive?: boolean;
+}
+export type OpfsWriteStatus = "created" | "skipped" | "updated";
+export interface OpfsWriteResult {
+    path: string;
+    status: OpfsWriteStatus;
+}
+export declare function getOpfsRootDirectory(): Promise<FileSystemDirectoryHandle>;
+export declare function getOpfsDirectoryHandle(path: string, options?: {
+    create?: boolean;
+    root?: FileSystemDirectoryHandle;
+}): Promise<FileSystemDirectoryHandle>;
+export declare function ensureOpfsDirectory(path: string): Promise<string>;
+export declare function ensureOpfsDirectories(paths: Iterable<string>): Promise<string[]>;
+export declare function opfsDirectoryExists(path: string): Promise<boolean>;
+export declare function opfsFileExists(path: string): Promise<boolean>;
+export declare function readOpfsFile(path: string): Promise<File>;
+export declare function readOpfsTextFile(path: string): Promise<string>;
+export declare function readOpfsTextLines(path: string, options?: {
+    maxLines?: number;
+}): Promise<string[]>;
+export declare function readOpfsJsonFile<T = unknown>(path: string): Promise<T>;
+export declare function writeOpfsFile(path: string, content: BlobPart | BlobPart[], options?: OpfsWriteOptions): Promise<OpfsWriteResult>;
+export declare function writeOpfsTextFile(path: string, text: string, options?: OpfsWriteOptions): Promise<OpfsWriteResult>;
+export declare function appendOpfsFile(path: string, content: BlobPart | BlobPart[], options?: Pick<OpfsWriteOptions, "createParents">): Promise<OpfsWriteResult>;
+export declare function appendOpfsTextFile(path: string, text: string, options?: Pick<OpfsWriteOptions, "createParents">): Promise<OpfsWriteResult>;
+export declare function writeOpfsJsonFile(path: string, value: unknown, options?: OpfsWriteOptions): Promise<OpfsWriteResult>;
+export declare function listOpfsDirectory(path: string): Promise<OpfsEntryInfo[]>;
+export declare function removeOpfsEntry(path: string, options?: OpfsRemoveOptions): Promise<string>;

package/dist/opfs/io.js

@@ -0,0 +1,156 @@
+import { joinOpfsPath, normalizeOpfsPath, opfsBasename, opfsDirname, splitOpfsPath, } from "./path.js";
+export async function getOpfsRootDirectory() {
+    if (!globalThis.navigator?.storage?.getDirectory) {
+        throw new Error("OPFS is not available in this environment.");
+    }
+    return navigator.storage.getDirectory();
+}
+export async function getOpfsDirectoryHandle(path, options = {}) {
+    const segments = splitOpfsPath(path);
+    let current = options.root ?? (await getOpfsRootDirectory());
+    for (const segment of segments) {
+        current = await current.getDirectoryHandle(segment, {
+            create: options.create,
+        });
+    }
+    return current;
+}
+export async function ensureOpfsDirectory(path) {
+    const normalizedPath = normalizeOpfsPath(path);
+    await getOpfsDirectoryHandle(normalizedPath, { create: true });
+    return normalizedPath;
+}
+export async function ensureOpfsDirectories(paths) {
+    const ensured = [];
+    for (const path of paths) {
+        ensured.push(await ensureOpfsDirectory(path));
+    }
+    return ensured;
+}
+export async function opfsDirectoryExists(path) {
+    try {
+        await getOpfsDirectoryHandle(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function opfsFileExists(path) {
+    try {
+        const parent = await getOpfsDirectoryHandle(opfsDirname(path));
+        await parent.getFileHandle(opfsBasename(path));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readOpfsFile(path) {
+    const parent = await getOpfsDirectoryHandle(opfsDirname(path));
+    const handle = await parent.getFileHandle(opfsBasename(path));
+    return handle.getFile();
+}
+export async function readOpfsTextFile(path) {
+    return (await readOpfsFile(path)).text();
+}
+export async function readOpfsTextLines(path, options = {}) {
+    const lines = (await readOpfsTextFile(path)).split(/\r?\n/);
+    return options.maxLines === undefined
+        ? lines
+        : lines.slice(0, options.maxLines);
+}
+export async function readOpfsJsonFile(path) {
+    return JSON.parse(await readOpfsTextFile(path));
+}
+export async function writeOpfsFile(path, content, options = {}) {
+    const normalizedPath = normalizeOpfsPath(path);
+    const overwrite = options.overwrite ?? true;
+    const exists = await opfsFileExists(normalizedPath);
+    if (exists && !overwrite) {
+        return { path: normalizedPath, status: "skipped" };
+    }
+    const parentPath = opfsDirname(normalizedPath);
+    const parent = options.createParents === false
+        ? await getOpfsDirectoryHandle(parentPath)
+        : await getOpfsDirectoryHandle(parentPath, { create: true });
+    const handle = await parent.getFileHandle(opfsBasename(normalizedPath), {
+        create: true,
+    });
+    const writable = await handle.createWritable();
+    await writable.write(Array.isArray(content) ? new Blob(content) : content);
+    await writable.close();
+    return { path: normalizedPath, status: exists ? "updated" : "created" };
+}
+export async function writeOpfsTextFile(path, text, options = {}) {
+    return writeOpfsFile(path, text, options);
+}
+export async function appendOpfsFile(path, content, options = {}) {
+    const normalizedPath = normalizeOpfsPath(path);
+    const exists = await opfsFileExists(normalizedPath);
+    const parentPath = opfsDirname(normalizedPath);
+    const parent = options.createParents === false
+        ? await getOpfsDirectoryHandle(parentPath)
+        : await getOpfsDirectoryHandle(parentPath, { create: true });
+    const handle = await parent.getFileHandle(opfsBasename(normalizedPath), {
+        create: true,
+    });
+    const writable = await handle.createWritable({ keepExistingData: true });
+    if (exists) {
+        const file = await handle.getFile();
+        await writable.seek(file.size);
+    }
+    await writable.write(Array.isArray(content) ? new Blob(content) : content);
+    await writable.close();
+    return { path: normalizedPath, status: exists ? "updated" : "created" };
+}
+export async function appendOpfsTextFile(path, text, options = {}) {
+    return appendOpfsFile(path, text, options);
+}
+export async function writeOpfsJsonFile(path, value, options = {}) {
+    return writeOpfsTextFile(path, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+export async function listOpfsDirectory(path) {
+    const normalizedPath = normalizeOpfsPath(path);
+    const directory = await getOpfsDirectoryHandle(normalizedPath);
+    const entries = [];
+    for await (const [name, handle] of directory.entries()) {
+        const childPath = joinOpfsPath(normalizedPath, name);
+        if (handle.kind === "directory") {
+            entries.push({
+                kind: "directory",
+                lastModified: 0,
+                name,
+                path: childPath,
+                size: 0,
+                type: "",
+            });
+            continue;
+        }
+        const fileHandle = handle;
+        const file = await fileHandle.getFile();
+        entries.push({
+            kind: "file",
+            lastModified: file.lastModified,
+            name,
+            path: childPath,
+            size: file.size,
+            type: file.type,
+        });
+    }
+    return entries.sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === "directory" ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+}
+export async function removeOpfsEntry(path, options = {}) {
+    const normalizedPath = normalizeOpfsPath(path);
+    const name = opfsBasename(normalizedPath);
+    if (!name) {
+        throw new Error("Cannot remove OPFS root directory.");
+    }
+    const parent = await getOpfsDirectoryHandle(opfsDirname(normalizedPath));
+    await parent.removeEntry(name, { recursive: options.recursive ?? false });
+    return normalizedPath;
+}

package/dist/opfs/layout.d.ts

@@ -0,0 +1,50 @@
+export declare const ziioOpfsLayoutVersion = 1;
+export declare const defaultZiioOpfsUserId = "default";
+export declare const ziioOpfsSharedKinds: readonly ["skills", "functions", "notes", "mcp", "libs"];
+export type ZiioOpfsSharedKind = (typeof ziioOpfsSharedKinds)[number];
+export interface ZiioOpfsUserPaths {
+    userId: string;
+    userRoot: string;
+    home: string;
+    documents: string;
+    downloads: string;
+    workspace: string;
+    appDataRoot: string;
+    cacheRoot: string;
+    tmpRoot: string;
+}
+export interface ZiioOpfsAppPaths extends ZiioOpfsUserPaths {
+    appId: string;
+    appInstall: string;
+    appData: string;
+    appCache: string;
+    appTmp: string;
+    sharedRoot: string;
+    sharedSkills: string;
+    sharedFunctions: string;
+    sharedNotes: string;
+    sharedMcp: string;
+    sharedLibs: string;
+}
+export declare const ziioOpfsSystemPaths: {
+    readonly systemRoot: "/.ziio";
+    readonly fsRegistry: "/.ziio/fs.json";
+    readonly appsRegistry: "/.ziio/apps.json";
+    readonly usersRegistry: "/.ziio/users.json";
+    readonly migrations: "/.ziio/migrations";
+    readonly trash: "/.ziio/trash";
+    readonly tmp: "/.ziio/tmp";
+};
+export declare function assertZiioOpfsName(name: string, label?: string): string;
+export declare function getZiioOpfsUserPaths(userId?: string): ZiioOpfsUserPaths;
+export declare function getZiioOpfsAppPaths(appId: string, options?: {
+    userId?: string;
+}): ZiioOpfsAppPaths;
+export declare function getZiioOpfsBaseDirs(options?: {
+    userId?: string;
+    sharedKinds?: readonly ZiioOpfsSharedKind[];
+}): string[];
+export declare function getZiioOpfsAppDirs(appId: string, options?: {
+    userId?: string;
+    sharedKinds?: readonly ZiioOpfsSharedKind[];
+}): string[];

package/dist/opfs/layout.js

@@ -0,0 +1,98 @@
+import { joinOpfsPath } from "./path.js";
+const invalidZiioOpfsNameRe = /[\\/\0]/;
+export const ziioOpfsLayoutVersion = 1;
+export const defaultZiioOpfsUserId = "default";
+export const ziioOpfsSharedKinds = [
+    "skills",
+    "functions",
+    "notes",
+    "mcp",
+    "libs",
+];
+export const ziioOpfsSystemPaths = {
+    systemRoot: "/.ziio",
+    fsRegistry: "/.ziio/fs.json",
+    appsRegistry: "/.ziio/apps.json",
+    usersRegistry: "/.ziio/users.json",
+    migrations: "/.ziio/migrations",
+    trash: "/.ziio/trash",
+    tmp: "/.ziio/tmp",
+};
+export function assertZiioOpfsName(name, label = "name") {
+    const trimmed = name.trim();
+    if (!trimmed) {
+        throw new Error(`OPFS ${label} must not be empty.`);
+    }
+    if (invalidZiioOpfsNameRe.test(trimmed) ||
+        trimmed === "." ||
+        trimmed === "..") {
+        throw new Error(`Invalid OPFS ${label}: ${name}`);
+    }
+    return trimmed;
+}
+export function getZiioOpfsUserPaths(userId = defaultZiioOpfsUserId) {
+    const safeUserId = assertZiioOpfsName(userId, "user id");
+    const userRoot = joinOpfsPath("/users", safeUserId);
+    return {
+        userId: safeUserId,
+        userRoot,
+        home: joinOpfsPath(userRoot, "home"),
+        documents: joinOpfsPath(userRoot, "home", "documents"),
+        downloads: joinOpfsPath(userRoot, "home", "downloads"),
+        workspace: joinOpfsPath(userRoot, "home", "workspace"),
+        appDataRoot: joinOpfsPath(userRoot, "app-data"),
+        cacheRoot: joinOpfsPath(userRoot, "cache"),
+        tmpRoot: joinOpfsPath(userRoot, "tmp"),
+    };
+}
+export function getZiioOpfsAppPaths(appId, options = {}) {
+    const safeAppId = assertZiioOpfsName(appId, "app id");
+    const userPaths = getZiioOpfsUserPaths(options.userId);
+    const sharedRoot = "/shared";
+    return {
+        ...userPaths,
+        appId: safeAppId,
+        appInstall: joinOpfsPath("/apps", safeAppId),
+        appData: joinOpfsPath(userPaths.appDataRoot, safeAppId),
+        appCache: joinOpfsPath(userPaths.cacheRoot, safeAppId),
+        appTmp: joinOpfsPath(userPaths.tmpRoot, safeAppId),
+        sharedRoot,
+        sharedSkills: joinOpfsPath(sharedRoot, "skills"),
+        sharedFunctions: joinOpfsPath(sharedRoot, "functions"),
+        sharedNotes: joinOpfsPath(sharedRoot, "notes"),
+        sharedMcp: joinOpfsPath(sharedRoot, "mcp"),
+        sharedLibs: joinOpfsPath(sharedRoot, "libs"),
+    };
+}
+export function getZiioOpfsBaseDirs(options = {}) {
+    const userPaths = getZiioOpfsUserPaths(options.userId);
+    const sharedKinds = options.sharedKinds ?? ziioOpfsSharedKinds;
+    return [
+        ziioOpfsSystemPaths.systemRoot,
+        ziioOpfsSystemPaths.migrations,
+        ziioOpfsSystemPaths.trash,
+        ziioOpfsSystemPaths.tmp,
+        "/users",
+        userPaths.userRoot,
+        userPaths.home,
+        userPaths.documents,
+        userPaths.downloads,
+        userPaths.workspace,
+        userPaths.appDataRoot,
+        userPaths.cacheRoot,
+        userPaths.tmpRoot,
+        "/shared",
+        ...sharedKinds.map((kind) => joinOpfsPath("/shared", kind)),
+        "/apps",
+    ];
+}
+export function getZiioOpfsAppDirs(appId, options = {}) {
+    const appPaths = getZiioOpfsAppPaths(appId, options);
+    return [
+        ...getZiioOpfsBaseDirs(options),
+        appPaths.appInstall,
+        appPaths.appData,
+        appPaths.appCache,
+        appPaths.appTmp,
+    ];
+}

package/dist/opfs/path.d.ts

@@ -0,0 +1,8 @@
+export declare function splitOpfsPath(path: string): string[];
+export declare function normalizeOpfsPath(path: string): string;
+export declare function normalizeRelativeOpfsPath(path: string): string;
+export declare function joinOpfsPath(...parts: Array<number | string>): string;
+export declare function joinRelativeOpfsPath(...parts: Array<number | string>): string;
+export declare function opfsBasename(path: string): string;
+export declare function opfsDirname(path: string): string;
+export declare function stripOpfsPrefix(path: string, prefix: string): string;

package/dist/opfs/path.js

@@ -0,0 +1,52 @@
+const nullByteRe = /\0/;
+export function splitOpfsPath(path) {
+    if (nullByteRe.test(path)) {
+        throw new Error("OPFS path must not contain null bytes.");
+    }
+    return path
+        .replace(/\\/g, "/")
+        .split("/")
+        .filter((part) => part.length > 0 && part !== ".")
+        .map((part) => {
+        if (part === "..") {
+            throw new Error("OPFS path must not contain '..' segments.");
+        }
+        return part;
+    });
+}
+export function normalizeOpfsPath(path) {
+    const segments = splitOpfsPath(path);
+    return segments.length > 0 ? `/${segments.join("/")}` : "/";
+}
+export function normalizeRelativeOpfsPath(path) {
+    return splitOpfsPath(path).join("/");
+}
+export function joinOpfsPath(...parts) {
+    return normalizeOpfsPath(parts.filter((part) => String(part)).join("/"));
+}
+export function joinRelativeOpfsPath(...parts) {
+    return normalizeRelativeOpfsPath(parts.filter((part) => String(part)).join("/"));
+}
+export function opfsBasename(path) {
+    return splitOpfsPath(path).at(-1) ?? "";
+}
+export function opfsDirname(path) {
+    const segments = splitOpfsPath(path);
+    segments.pop();
+    return segments.length > 0 ? `/${segments.join("/")}` : "/";
+}
+export function stripOpfsPrefix(path, prefix) {
+    const normalizedPath = normalizeOpfsPath(path);
+    const normalizedPrefix = normalizeOpfsPath(prefix);
+    if (normalizedPrefix === "/") {
+        return normalizeRelativeOpfsPath(normalizedPath);
+    }
+    if (normalizedPath === normalizedPrefix) {
+        return "";
+    }
+    const prefixWithSlash = `${normalizedPrefix}/`;
+    if (!normalizedPath.startsWith(prefixWithSlash)) {
+        throw new Error(`OPFS path "${normalizedPath}" is outside prefix "${normalizedPrefix}".`);
+    }
+    return normalizeRelativeOpfsPath(normalizedPath.slice(prefixWithSlash.length));
+}

package/dist/opfs/volume.d.ts

@@ -0,0 +1,19 @@
+import { type ZiioOpfsSharedKind } from "./layout.js";
+export interface ZiioOpfsFsRegistry {
+    kind: "ziio.opfs";
+    version: number;
+    users: string[];
+    apps: string[];
+    updatedAt: string;
+}
+export interface EnsureZiioOpfsLayoutOptions {
+    appIds?: readonly string[];
+    userId?: string;
+    sharedKinds?: readonly ZiioOpfsSharedKind[];
+    now?: Date;
+}
+export interface EnsureZiioOpfsLayoutResult {
+    directories: string[];
+    registry: ZiioOpfsFsRegistry;
+}
+export declare function ensureZiioOpfsLayout(options?: EnsureZiioOpfsLayoutOptions): Promise<EnsureZiioOpfsLayoutResult>;

package/dist/opfs/volume.js

@@ -0,0 +1,42 @@
+import { ensureOpfsDirectories, readOpfsJsonFile, writeOpfsJsonFile, } from "./io.js";
+import { getZiioOpfsAppDirs, getZiioOpfsBaseDirs, ziioOpfsLayoutVersion, ziioOpfsSystemPaths, } from "./layout.js";
+export async function ensureZiioOpfsLayout(options = {}) {
+    const appIds = [...(options.appIds ?? [])];
+    const dirs = appIds.length > 0
+        ? appIds.flatMap((appId) => getZiioOpfsAppDirs(appId, options))
+        : getZiioOpfsBaseDirs(options);
+    const directories = await ensureOpfsDirectories([...new Set(dirs)]);
+    const registry = await upsertZiioOpfsFsRegistry(options);
+    return { directories, registry };
+}
+async function upsertZiioOpfsFsRegistry(options) {
+    const now = (options.now ?? new Date()).toISOString();
+    let registry = {
+        kind: "ziio.opfs",
+        version: ziioOpfsLayoutVersion,
+        users: [],
+        apps: [],
+        updatedAt: now,
+    };
+    try {
+        registry = await readOpfsJsonFile(ziioOpfsSystemPaths.fsRegistry);
+    }
+    catch {
+        // Missing or unreadable registry is recreated from the requested layout.
+    }
+    const users = new Set(registry.users);
+    users.add(options.userId ?? "default");
+    const apps = new Set(registry.apps);
+    for (const appId of options.appIds ?? []) {
+        apps.add(appId);
+    }
+    registry = {
+        kind: "ziio.opfs",
+        version: ziioOpfsLayoutVersion,
+        users: [...users].sort(),
+        apps: [...apps].sort(),
+        updatedAt: now,
+    };
+    await writeOpfsJsonFile(ziioOpfsSystemPaths.fsRegistry, registry);
+    return registry;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ziioapp/os-features",
+  "version": "0.1.0",
+  "description": "Browser file utilities and ZiioApp OPFS layout helpers",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./files/*": {
+      "types": "./dist/files/*.d.ts",
+      "import": "./dist/files/*.js"
+    },
+    "./opfs": {
+      "types": "./dist/opfs/index.d.ts",
+      "import": "./dist/opfs/index.js"
+    },
+    "./opfs/*": {
+      "types": "./dist/opfs/*.d.ts",
+      "import": "./dist/opfs/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "jschardet": "^3.1.4"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "author": "ziioai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ziioai/ziioos.git",
+    "directory": "packages/os-features"
+  },
+  "homepage": "https://github.com/ziioai/ziioos#readme",
+  "bugs": {
+    "url": "https://github.com/ziioai/ziioos/issues"
+  },
+  "keywords": [
+    "opfs",
+    "browser",
+    "filesystem",
+    "ziioapp"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "node ../../scripts/build-package.mjs"
+  }
+}