@hivecast/stream-shell (1.1.33)
Installation
@hivecast:registry=npm install @hivecast/stream-shell@1.1.33"@hivecast/stream-shell": "1.1.33"About this package
Stream
Stream is an optional ordinary application that arranges live actor views as cards or a continuous feed. Use it for a review queue, interactive learning, a collection of tools or a feed. It does not inherit the desktop kernel. Opening another card changes attention; it never approves a request, ends a workflow or stops the source actor.
Open Stream from Start, choose Browse this home, or Connect a collection.
An author supplies a collection/v1 keeper and an optional parent row. The
keeper remains responsible for order, permissions and cursor paging. Each row
with an address opens its own discovered Explorer views; an unaddressed row
shows its description. A missing or denied view keeps the existing sheet's
explanation. No author needs to write HTML or a new view for every card.
Choose Stream layout: vertical cards, horizontal cards or continuous feed.
Swipe across a deck card, use Previous/Next, or focus its title and press
arrow keys. The card follows a deliberate swipe; a tap never navigates. Mouse dragging is
separate from wheel/trackpad scrolling. On touchscreens, scrollable content gets
the whole stroke while it has room in that direction. At an edge, a
fresh swipe can move cards. Inputs, sliders, media, draggable widgets and text
selection keep their own interactions; pinch and long press do not navigate.
Changing layouts keeps the same recent live documents. Continuous feed remains
native scrolling. Admitted app documents offer unused gestures through their actual
host frame, so nesting gives the nearest deck first refusal. A custom gesture
widget can consume its input or declare data-swipe="ignore". Opaque sandboxed
frames keep their own input; use the surrounding card or Previous/Next there.
Close Stream returns a normal view outcome to its opener.
The page is an actor. Its operations are the same ones used by the buttons:
| Operation | Inputs | Purpose |
|---|---|---|
stream.open |
title, sourceRoot, sourceMount, collection, optional parent, axis, presentation, facet |
Open a collection; axis is vertical or horizontal; presentation is deck (default) or feed |
stream.describe |
none | Current definition, exact active row/subject/occurrence, loaded rows, page availability and actual resident views |
stream.select |
key |
Select an occurrence on the loaded page |
stream.next, stream.previous |
none | Move attention, fetching the keeper's next page when needed |
stream.axis |
axis |
Change navigation direction in place |
stream.close |
none | Return the selected occurrence and finish this view |
stream.release |
key, optional discard: true |
Explicitly close one retained card; consent is required for a kept app or dirty view |
stream.layout |
presentation |
Change between deck and feed while preserving retained live views |
stream.more |
none | Read the next owner page |
stream.refresh |
none | Apply the source's changed rows to the bounded current window |
Recent views stay mounted in a four-view pool. Revisit one to retain its DOM
state. When the pool fills, only a view that answers canLeave() is released.
Whole application cards remain pinned until explicitly closed through Live;
Stream cannot assume it can capture an arbitrary app's private state. If every
candidate is pinned or has unkept edits, release a card before proceeding. A
dirty or pinned view removed from the source is retained.
Closing/replacing a stream respects that same guard. This is supported live
state retention, not a universal snapshot of arbitrary applications.
The continuous feed starts with lightweight previews. Use this card expands the actual discovered view in place; several live tools can be visible together, within the same four-view budget. Focus selects the active occurrence for an agent. Near the end, the feed asks the keeper for its next cursor. Load more also works without scrolling; an exhausted source says you're caught up.
Source notifications offer a refresh choice above the feed while you read or type, leaving embedded app controls uncovered. Refresh reconciles stable occurrence keys and preserves the first surviving reading anchor. Retained cards receive their current source titles, kinds and summaries, including reply counts, without replacing their live views or private drafts. A ResizeObserver holds that anchor when content above it changes height. Changing layout uses the browser's state-preserving DOM move; a browser lacking that capability refuses to move connected live views rather than reload their documents. This is separate from disposing a view or stopping its source actor.
Metadata has a 96-row reading window, fetched 16 rows at a time through the owner's opaque cursor. Refresh reads at most those six retained owner pages and commits only after all have answered. Long-running traversal releases earlier metadata; reopen the collection to return to its beginning. Removing Stream releases only its own views and collection subscription. It leaves domain actors and already-sent work with their existing owners.
For a containing app, StreamPageElement.openSource(definition, source) accepts
an already admitted CollectionSource. For scripts/agents, send the operations
above to this page's actual actor address. Its declared stream/v1 interface,
thing facts and native cognitive state expose the selected tool and exact source
to discovery and subsequent agent turns. No separate awareness store is used.
Demos S32 contains the complete live-deck-tour Lisp function, narration,
breakpoints and semantic assertions. liveDeckProgram(receiver) supplies an
existing Stream component's actual actor address to that same function; without
one, it discovers/opens the ordinary optional app. An example refuses to replace
an existing nonempty Stream and closes only the view it owns.
Demos S33 is the continuous-feed counterpart. Its complete Lisp observes the actual Shell window collection, opens Canvas, applies the actual source update, and closes Canvas only when the example opened that window. The function accepts an existing Stream receiver and the enclosing application's name, so the same script also runs inside another app. The actor and its source remain ordinary components; no feed-specific backend or second Shell session is created.
pnpm --dir applications/stream-shell test
pnpm --dir applications/stream-shell type-check
pnpm --dir applications/stream-shell build
The package uses the standard application manifest, runtime factory, browser
module provider and shared browser-manifest finalizer. During development,
hivedock up in this directory projects it as a normal folder-run application;
the desktop bundle has no import of Stream.
Demos S34, A desktop inside a live card, is the complete nested-workspace example. Its Lisp opens the installed Zoom Shell through the same Application tab as any other app. Inner application navigation and view exits stay local; releasing the card leaves the outer desktop and independently owned actors running. The source journey exercises this same program at phone, portrait and landscape sizes, including an actual Explorer draft across a Canvas switch.
A nested Zoom Shell receives an owner-issued view occurrence, shares admitted byte loading and borrows the containing page's resolved session. It does not attach the ambient desktop session or write its own session into the browser URL. Creating this workspace is distinct from moving or restoring an existing live desktop. Keep a copy of the Lisp to reconstruct its definition; private application drafts are retained only while their supported live views remain.
The same component also runs in the Open on its own app-only entrance from
Quick Open, with no desktop underneath. Keep Stream installed in that home for
normal catalogue launch. The containing page supplies the same scoped hosting
and declared-view services, rather than Stream inheriting a kernel. A separate
placement constructs a new view; returning to an already live occurrence keeps
it. To reconstruct a collection definition later, keep its Lisp function using
the existing keep-word facility, and pass the new view's actual receiver:
(define (review-tools view source-root)
(request view "stream.open" "title" "Tools to review"
"sourceRoot" source-root "sourceMount" "system.registry"
"collection" "things" "presentation" "feed" "axis" "vertical"))
This is the same checked operation in a desktop, an app-only page or a nested component. It records the source and presentation; it captures no credential, native handle or arbitrary application's private state. Package custom views with their ordinary manifest declarations; standard installed views are resolved from the same catalogue and view registry in each supported host.
stream.describe also returns close, the same ViewCloseAnswer used by the
view’s existing close guard. A script can check may-close before releasing its
owned resources. Closing a view can change its Shell context; do that last, after
other addressed cleanup, rather than continuing to issue operations in an old
context. A needs-person answer leaves both the view and its source work intact.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/conversation | 1.1.33 |
| @open-matrix/core | 1.1.33 |
| @open-matrix/dashboard-components | 1.1.33 |
| @open-matrix/explorer | 1.1.33 |
| @open-matrix/hivecast-brand | 1.1.33 |
Development Dependencies
| ID | Version |
|---|---|
| @open-matrix/hive-pm | 1.1.33 |
| @types/node | ^25.0.10 |
| esbuild | ^0.27.3 |
| linkedom | ^0.16.11 |
| tsx | ^4.21.0 |
| typescript | ^5.7.0 |