@enbox/create-dapp 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/create-dapp",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Create a minimal Enbox React application",
   "type": "module",
   "license": "Apache-2.0",

package/template/README.md

@@ -30,6 +30,11 @@ toolchain. Production builds precache the app shell for
 later offline visits; `npm run preview` serves that built app locally. Deploy
 the generated `dist` directory on an HTTPS origin with service worker support.
 
+This starter explicitly activates worker updates immediately in `src/sw.ts`.
+Apps with an update prompt, such as Notesd, approve activation after pending
+edits are persisted. `prepareBrowser()` waits for the current worker; it does
+not choose an application's update policy.
+
 You can also use `bun install` and `bun run dev`. No lockfile is generated
 until your first install. Commit the resulting `package-lock.json` or `bun.lock`;
 then use `npm ci` or `bun install --frozen-lockfile` in CI. Direct dependencies
@@ -47,24 +52,28 @@ The application follows the same feature-store structure as notesd:
 ```text
 src/
   app/
-    application.ts      # feature registration and wallet identity
-    runtime.ts          # one browser-lifetime application owner
+    application.ts      # features, wallet identity, and one application owner
     App.tsx             # connection shell and feature composition
   features/tasks/
     protocol.ts         # typed encrypted records and validation
-    store.ts            # shared resources, commands, and domain defaults
+    store.ts            # shared observations, commands, and domain defaults
     components/         # task board and its styles
-  shared/components/
+  components/           # reusable UI shared by features
     ProfileCard.tsx
   main.tsx
   sw.ts
 ```
 
-`defineApplication` derives the protocol manifest from registered stores.
-`getApplication()` creates one headless runtime over a native connection.
+`createApplication` derives the protocol manifest from registered stores and
+constructs the browser connection with the configured wallet identity.
+`getApplication()` keeps one headless runtime for the page lifetime.
 `main.tsx` waits for worker control before passing that runtime to
 `EnboxProvider application={...}`. The provider initializes the borrowed runtime;
-the application owns its lifetime. Development module replacement disposes it.
+the application owns its page lifetime. Component Fast Refresh is useful for UI
+edits, but replacing a connected runtime or its store/protocol definitions is
+not a supported hot-reload operation. Disconnect before changing those files,
+then reload the page. Apps with document writers, such as Notesd, drain edits
+as part of disconnecting.
 
 The profile card reads published profile information through `useProfile`.
 Names, images, settlement state, and image URL lifetimes belong to the SDK.
@@ -77,13 +86,18 @@ The replaceable task feature lives in `src/features/tasks`:
 - `protocol.ts` declares encrypted `project` and `project/task` records with
   payload validators. Tasks store a title and completion state.
 - `store.ts` declares one shared project collection and a task collection scoped
-  with `tasks.within(projectContextId)`. Creation and rename defaults live here.
-  Native resource commands share pending/error state across consumers.
+  with `tasks.within(projectContextId)`. Its `activeTasks` observation keeps
+  the chosen project's query live through `activeTasks.select`; parent metadata and
+  rows arrive together. Fixed and selected observations use the same SDK
+  implementation. Creation and rename helpers reuse each collection's commands and their
+  shared pending/error state; observed state includes pagination progress.
 - `components/TaskBoard.tsx` resolves the feature with `useFeature(TaskBoardStore)`
-  and reads resources or commands with `useStore`. Task details reuse loaded list
+  and reads observed data or commands with `useStore`. Task details reuse loaded list
   rows and acquire a bounded single-record observation for a selection outside
-  the retained window. Input drafts and UI selection remain in React.
+  the retained window. Input drafts and task-detail selection remain in React.
   Awaited handlers check command authorization before applying their UI result.
+  Reopened task details also use selection identity to reject an older panel’s
+  completion.
 - `components/tasks.css` styles the task feature. Shared app and profile styles
   live in `src/style.css`.
 
@@ -102,6 +116,10 @@ try {
 
 Handles belong to their authorization session. Resolve a fresh feature when
 that session changes. React's `useFeature` handles that replacement automatically.
+`activeTasks` owns its selected query until another project, null, or session
+retirement. Other features can declare observations with changing inputs through
+`observe({ source: (parent: string) => tasks.within(parent) })`;
+commands remain on canonical `tasks.within(parentContextId)` handles.
 
 To replace the task feature, register your own store in `app/application.ts`,
 delete `src/features/tasks`, and change the feature rendered by `app/App.tsx`.

package/template/package.json

@@ -10,8 +10,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@enbox/browser": "0.3.83",
-    "@enbox/react": "0.0.8",
+    "@enbox/browser": "0.3.85",
+    "@enbox/react": "0.0.10",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

package/template/src/app/App.tsx

@@ -3,7 +3,7 @@ import { useEffect } from 'react';
 
 import app from '../app.json' with { type: 'json' };
 import { TaskBoard } from '../features/tasks/components/TaskBoard.js';
-import { ProfileCard } from '../shared/components/ProfileCard.js';
+import { ProfileCard } from '../components/ProfileCard.js';
 
 export function App() {
   const connection = useEnboxConnection();

package/template/src/app/application.ts

@@ -1,7 +1,16 @@
-import { defineApplication } from '@enbox/browser';
+import { createApplication, type BrowserApplicationOptions } from '@enbox/browser';
 
 import app from '../app.json' with { type: 'json' };
 import { TaskBoardStore } from '../features/tasks/store.js';
 
-export const applicationDefinition = defineApplication({ stores: { tasks: TaskBoardStore } });
-export const wallet = { appName: app.name, applicationId: app.id };
+export const applicationOptions = {
+  stores: { tasks: TaskBoardStore },
+  wallet: { appName: app.name, applicationId: app.id },
+} satisfies BrowserApplicationOptions;
+
+let application: ReturnType<typeof createApplication> | undefined;
+
+/** One application owner for this page, shared by React and application controllers. */
+export function getApplication() {
+  return application ??= createApplication(applicationOptions);
+}

package/template/src/features/tasks/components/TaskBoard.tsx

@@ -1,3 +1,4 @@
+import type { StoreInstance } from '@enbox/browser';
 import { useFeature, useStore } from '@enbox/react';
 import { useState } from 'react';
 import type { FormEvent } from 'react';
@@ -5,12 +6,14 @@ import type { FormEvent } from 'react';
 import { TaskBoardStore } from '../store.js';
 import './tasks.css';
 
+type TaskState = ReturnType<StoreInstance<typeof TaskBoardStore>['activeTasks']['getSnapshot']>;
+
 export function TaskBoard({ disabled = false }: { disabled?: boolean }) {
   const board = useFeature(TaskBoardStore);
   const projects = useStore(board.projects);
-  const creation = useStore(board.createProject);
-  const paging = useStore(board.moreProjects);
-  const [projectContextId, setProjectContextId] = useState<string>();
+  const activeTasks = useStore(board.activeTasks);
+  const creation = useStore(board.projects.create);
+  const projectContextId = activeTasks.selection;
   const [name, setName] = useState('');
   const creating = creation.pendingCount > 0;
   const prompt = projects.status === 'loading' ? 'Loading projects…'
@@ -19,8 +22,11 @@ export function TaskBoard({ disabled = false }: { disabled?: boolean }) {
   async function addProject(event: FormEvent) {
     event.preventDefault();
     try {
-      const record = await board.createProject.run(name);
-      if (board.createProject.isCurrent()) { setProjectContextId(record.contextId); setName(''); }
+      const record = await board.createProject(name);
+      if (board.projects.create.isCurrent()) {
+        setName('');
+        await board.activeTasks.select(record.contextId);
+      }
     } catch { /* The command exposes the error below. */ }
   }
   return (
@@ -38,28 +44,28 @@ export function TaskBoard({ disabled = false }: { disabled?: boolean }) {
       {creation.error && <p role="alert">Couldn’t create the project: {creation.error.message}</p>}
       {projects.status === 'error' && <div role="alert">
         <p>Couldn’t load projects: {projects.error.message}</p>
-        <button type="button" disabled={disabled} onClick={() => { void board.retryProjects.run(); }}>Try again</button>
+        <button type="button" disabled={disabled} onClick={() => { void board.projects.retry().catch(() => {}); }}>Try again</button>
       </div>}
       <div className="project-picker" role="group" aria-label="Projects">
         {projects.records.map(({ record, value }) => <button type="button" className="button button-quiet" key={record.id} disabled={disabled}
-          aria-pressed={record.contextId === projectContextId} onClick={() => setProjectContextId(record.contextId)}>{value.name}</button>)}
+          aria-pressed={record.contextId === projectContextId} onClick={() => { void board.activeTasks.select(record.contextId).catch(() => {}); }}>{value.name}</button>)}
       </div>
-      {projects.hasMore && <button type="button" disabled={disabled || paging.pendingCount > 0}
-        onClick={() => { void board.moreProjects.run(); }}>More projects</button>}
-      {projectContextId !== undefined
-        ? <ProjectTasks key={projectContextId} within={projectContextId} disabled={disabled} />
+      {projects.hasMore && <button type="button" disabled={disabled || projects.isLoadingMore}
+        onClick={() => { void board.projects.loadMore().catch(() => {}); }}>More projects</button>}
+      {projectContextId !== null
+        ? <ProjectTasks key={projectContextId} within={projectContextId} tasks={activeTasks} disabled={disabled} />
         : <p role="status">{prompt}</p>}
     </section>
   );
 }
 
-function ProjectTasks({ within, disabled }: { within: string; disabled: boolean }) {
+function ProjectTasks({ within, tasks, disabled }: {
+  within: string; tasks: TaskState; disabled: boolean;
+}) {
   const board = useFeature(TaskBoardStore);
-  const resource = board.tasks.within(within);
-  const tasks = useStore(resource);
-  const creation = useStore(resource.create);
-  const updates = useStore(resource.patch);
-  const paging = useStore(board.moreTasks);
+  const taskCollection = board.tasks.within(within);
+  const creation = useStore(taskCollection.create);
+  const updates = useStore(taskCollection.patch);
   const [title, setTitle] = useState('');
   // Reopening the same record creates a new UI target for completion guards.
   const [selection, setSelection] = useState<{ id: string }>();
@@ -68,7 +74,7 @@ function ProjectTasks({ within, disabled }: { within: string; disabled: boolean
     event.preventDefault();
     try {
       const record = await board.createTask({ within, title });
-      if (resource.create.isCurrent()) { setSelection({ id: record.id }); setTitle(''); }
+      if (taskCollection.create.isCurrent()) { setSelection({ id: record.id }); setTitle(''); }
     } catch { /* The scoped create command exposes the error below. */ }
   }
   return <div className="project-content">
@@ -82,18 +88,18 @@ function ProjectTasks({ within, disabled }: { within: string; disabled: boolean
     {creation.error && <p role="alert">Couldn’t add the task: {creation.error.message}</p>}
     {updates.error && <p role="alert">Couldn’t update the task: {updates.error.message}</p>}
     {tasks.status === 'error' && <p role="alert">Couldn’t load tasks. <button type="button"
-      disabled={disabled} onClick={() => { void board.retryTasks.run(within); }}>Retry tasks</button></p>}
+      disabled={disabled} onClick={() => { void taskCollection.retry().catch(() => {}); }}>Retry tasks</button></p>}
     <ul className="task-list">
-      {tasks.records.map(({ record, value }) => <li key={record.id} data-completed={value.completed}>
+      {(tasks.records ?? []).map(({ record, value }) => <li key={record.id} data-completed={value.completed}>
         <input type="checkbox" aria-label={`Complete ${value.title}`} checked={value.completed}
-          disabled={disabled || updates.pendingVariables.some((input) => input.id === record.id)}
-          onChange={(event) => { void resource.patch.run({ id: record.id, patch: { completed: event.currentTarget.checked } }); }} />
+          disabled={disabled || updates.pendingInputs.some((input) => input.id === record.id)}
+          onChange={(event) => { void taskCollection.patch.run({ id: record.id, patch: { completed: event.currentTarget.checked } }).catch(() => {}); }} />
         <button type="button" className="button button-quiet" aria-label={`Open task ${value.title}`}
           disabled={disabled} aria-pressed={record.id === selection?.id} onClick={() => setSelection({ id: record.id })}>{value.title}</button>
       </li>)}
     </ul>
-    {tasks.hasMore && <button type="button" disabled={disabled || paging.pendingVariables.includes(within)}
-      onClick={() => { void board.moreTasks.run(within); }}>More tasks</button>}
+    {tasks.hasMore && <button type="button" disabled={disabled || tasks.isLoadingMore}
+      onClick={() => { void taskCollection.loadMore().catch(() => {}); }}>More tasks</button>}
     {selection !== undefined
       ? <TaskDetails key={selection.id} within={within} recordId={selection.id} disabled={disabled}
         onClose={() => setSelection((current) => current === selection ? undefined : current)} />
@@ -105,31 +111,32 @@ function TaskDetails({ within, recordId, disabled, onClose }: {
   within: string; recordId: string; disabled: boolean; onClose: () => void;
 }) {
   const board = useFeature(TaskBoardStore);
-  const resource = board.tasks.within(within);
-  const list = useStore(resource);
+  const taskCollection = board.tasks.within(within);
+  const list = useStore(taskCollection);
   const listed = list.records.some((row) => row.record.id === recordId);
   // A bounded window cannot prove an unlisted record is missing. Reuse loaded
   // rows, and acquire a single-record view only while that proof is unavailable.
   const needsLookup = !listed && (list.status !== 'ready' || list.hasMore);
-  const selection = useStore(needsLookup ? board.taskById(within, recordId) : resource);
-  const task = selection.records.find((row) => row.record.id === recordId);
-  const status = selection.status;
-  const updates = useStore(resource.patch);
-  const deletion = useStore(resource.delete);
+  const lookup = needsLookup ? board.taskById(within, recordId) : null;
+  const details = useStore(lookup, { fallback: list });
+  const task = details.records.find((row) => row.record.id === recordId);
+  const status = details.status;
+  const updates = useStore(taskCollection.patch);
+  const deletion = useStore(taskCollection.delete);
   const [draft, setDraft] = useState<string>();
-  const pending = updates.pendingVariables.some((input) => input.id === recordId) || deletion.pendingVariables.includes(recordId);
+  const pending = updates.pendingInputs.some((input) => input.id === recordId) || deletion.pendingInputs.includes(recordId);
   async function saveTitle(event: FormEvent) {
     event.preventDefault();
     if (draft === undefined) return;
     try {
       await board.renameTask({ within, id: recordId, title: draft });
-      if (resource.patch.isCurrent()) setDraft(undefined);
+      if (taskCollection.patch.isCurrent()) setDraft(undefined);
     } catch { /* The scoped patch command exposes the error below. */ }
   }
   async function deleteTask() {
     try {
-      await resource.delete.run(recordId);
-      if (resource.delete.isCurrent()) onClose();
+      await taskCollection.delete.run(recordId);
+      if (taskCollection.delete.isCurrent()) onClose();
     } catch { /* The scoped delete command exposes the error below. */ }
   }
   const data = task?.value;
@@ -137,8 +144,7 @@ function TaskDetails({ within, recordId, disabled, onClose }: {
     <h3>Task details</h3>
     {status === 'error' && <p role="alert">Couldn’t load the task. <button type="button"
       disabled={disabled} onClick={() => {
-        if (needsLookup) void board.retryTask.run({ within, recordId });
-        else void board.retryTasks.run(within);
+        void (lookup ?? taskCollection).retry().catch(() => {});
       }}>Retry task</button></p>}
     {data === undefined && status === 'loading' && <p role="status">Loading task…</p>}
     {data === undefined && status === 'ready' && <p role="status">This task is no longer available.</p>}

package/template/src/features/tasks/store.ts

@@ -2,12 +2,13 @@ import { DateSort, defineStore } from '@enbox/browser';
 
 import { TaskBoardProtocol } from './protocol.js';
 
-/** Protocol resources and domain defaults are shared with every consumer. */
+/** Protocol observations and domain defaults are shared with every consumer. */
 export const TaskBoardStore = defineStore({
   protocols: { board: TaskBoardProtocol },
-  create({ protocols, command }) {
+  create({ protocols, observe }) {
     const projects = protocols.board.collection('project', { dateSort: DateSort.CreatedDescending });
     const tasks = protocols.board.collection('project/task');
+    const activeTasks = observe({ source: (parent: string) => tasks.within(parent) });
     const taskById = (within: string, recordId: string) => protocols.board.collection('project/task', {
       filter: { recordId }, pagination: { limit: 1 },
     }).within(within);
@@ -15,17 +16,13 @@ export const TaskBoardStore = defineStore({
     return {
       projects,
       tasks,
+      activeTasks,
       taskById,
-      createProject: command((name: string) => projects.create.run({ name: name.trim() })),
+      createProject: (name: string) => projects.create.run({ name: name.trim() }),
       createTask: ({ within, title }: { within: string; title: string }) =>
         tasks.within(within).create.run({ title: title.trim(), completed: false }),
       renameTask: ({ within, id, title }: { within: string; id: string; title: string }) =>
         tasks.within(within).patch.run({ id, patch: { title: title.trim() } }),
-      moreProjects: command(() => projects.loadMore()),
-      moreTasks: command((within: string) => tasks.within(within).loadMore()),
-      retryProjects: command(() => projects.retry()),
-      retryTasks: command((within: string) => tasks.within(within).retry()),
-      retryTask: command(({ within, recordId }: { within: string; recordId: string }) => taskById(within, recordId).retry()),
     };
   },
 });

package/template/src/main.tsx

@@ -4,7 +4,7 @@ import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 
 import { App } from './app/App.js';
-import { getApplication } from './app/runtime.js';
+import { getApplication } from './app/application.js';
 import workerPath from './sw.ts?worker&url';
 import './style.css';
 

package/template/src/sw.ts

@@ -36,5 +36,7 @@ if (import.meta.env.PROD) {
   });
 }
 
-// The current browser SDK performs automatic worker takeover.
+// This starter activates updates immediately. Apps with an update prompt should
+// call skipWaiting only after the user accepts and pending edits are persisted.
+self.addEventListener('install', (event) => { event.waitUntil(self.skipWaiting()); });
 activatePolyfills({ onCacheCheck: () => ({ ttl: 30_000 }) });

package/template/src/app/runtime.ts

@@ -1,17 +0,0 @@
-import { BrowserConnectHandler, createApplication, createConnectionStore } from '@enbox/browser';
-
-import { applicationDefinition, wallet } from './application.js';
-
-let runtime: ReturnType<typeof createApplication> | undefined;
-
-/** One browser-lifetime owner shared by React and application controllers. */
-export function getApplication() {
-  return runtime ??= createApplication(applicationDefinition, {
-    connection: createConnectionStore({
-      application: applicationDefinition.manifest,
-      connectHandler: BrowserConnectHandler(wallet),
-    }),
-  });
-}
-
-if (import.meta.hot) import.meta.hot.dispose(() => { void runtime?.dispose(); });