@netscript/fresh-ui

Fresh UI registry seams and interactive foundations for NetScript. This page is written against the package public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The root entrypoint (@netscript/fresh-ui) intentionally stays small: copy-based registry components and islands remain on workspace-local deep paths so applications can own and evolve them after copy. The root module exposes only the supported helper utilities that are safe to consume as package runtime dependencies. Five sub-path exports carry the package runtime seams:

• @netscript/fresh-ui/ai/render-ui — safe, bounded generative-UI renderer for validated tool payloads.
• @netscript/fresh-ui/desktop — browser-safe native desktop chrome helpers.
• @netscript/fresh-ui/interactive — package-owned interactive namespaces for stateful, accessible primitives.
• @netscript/fresh-ui/primitives — L0 platform-contract primitives.
• @netscript/fresh-ui/registry — embedded copy-registry manifest and file content.

Class-name helper

Icon primitive

Icon is a first-class stroke-SVG icon primitive, re-exported at the package root alongside its supporting types from @netscript/fresh-ui/primitives.

DataGrid

DataGrid is a generic, templated data-grid component exported from the package root (@netscript/fresh-ui) — the successor to the earlier DataTable registry block. Unlike the copy-source registry items, DataGrid is a runtime export you import directly; you do not netscript ui:add it. It renders a token-styled role="grid" region from a columns contract and a rows contract, and supports plain, button, and Fresh client-navigation rows.

DataGrid props

DataGridColumn<T>

DataGridRow<T>

Every row carries a stable id, a caller-owned data: T payload, and an optional selected flag. A row renders differently based on which navigation field is present — the three shapes are mutually exclusive (supply at most one of onSelect or href):

DataGrid symbols

DataGrid example

import { DataGrid, type DataGridColumn, type DataGridRow } from "@netscript/fresh-ui";

interface Invoice {
  id: string;
  customer: string;
  total: number;
}

const columns: DataGridColumn<Invoice>[] = [
  { key: "customer", header: "Customer", width: "2fr", cell: "strong" },
  { key: "total", header: "Total", cell: "num", render: (row) => `$${row.total.toFixed(2)}` },
];

const rows: DataGridRow<Invoice>[] = [
  { id: "inv-1", data: { id: "inv-1", customer: "Acme", total: 420 }, href: "/invoices/inv-1" },
  { id: "inv-2", data: { id: "inv-2", customer: "Globex", total: 130 }, selected: true, href: "/invoices/inv-2" },
];

export function InvoiceGrid() {
  return <DataGrid label="Invoices" columns={columns} rows={rows} />;
}

A column with cell: "num" renders monospace and right-aligned; cell: "strong" renders bold. A column without render falls back to row.data[column.key] when that key holds a string, number, bigint, boolean, null, or undefined.

Rows are keyed by id. Supply a stable id per row so Preact can reconcile rows across re-renders, and provide at most one of onSelect or href — the row shapes are mutually exclusive, and a link row navigates through Fresh (f-client-nav) rather than a full page load.

Dropzone (registry component)

Dropzone is a copy-source registry component, not a package export — install it with netscript ui:add dropzone, after which it lives at components/ui/dropzone.tsx in your app and is yours to edit. It renders a dashed file-drop target (<label class="ns-dropzone">) that ingests files from three sources — drag-and-drop, focused clipboard paste, and the native file picker — and filters each ingest through a shared accept / multiple policy before calling back.

Dropzone props

DropzoneProps also extends JSX.HTMLAttributes<HTMLLabelElement> (minus class, onDrop, onDragOver, and onPaste, which the component owns), so standard label attributes pass through.

Dropzone ingest types

Dropzone example

import { Dropzone, type DropzoneIngestDetails } from "@app/components/ui/dropzone.tsx";

export function AvatarUpload() {
  function handleFiles(files: readonly File[], details: DropzoneIngestDetails) {
    console.log(`Accepted ${files.length} file(s) via ${details.source}`);
    for (const rejected of details.rejectedFiles) {
      console.warn(`Rejected ${rejected.file.name}: ${rejected.reason}`);
    }
  }

  return (
    <Dropzone
      label="Drop images or click to upload"
      hint="PNG or JPG, up to 5 MB"
      accept="image/png,image/jpeg"
      multiple
      onFiles={handleFiles}
    />
  );
}

Rejections are reported, not silent: a file whose type falls outside accept is rejected with reason "type", and — when multiple is false — every file after the first is rejected with reason "too-many". Each ingest also updates a visually-rendered aria-live status node so assistive technology hears how many files were accepted or rejected.

Paste ingest requires focus. Clipboard paste only fires while the dropzone (or a child) holds focus, so pair it with a focusable affordance. The picker <input> clears its value after each selection, so re-selecting the same file still triggers onFile / onFiles.

Redirect-flash (toast) helpers

Toast types

Interactive namespaces

Exported from the @netscript/fresh-ui/interactive sub-path. Each is a compound namespace bundling a root component with its structural subcomponents. The namespace types are package-internal (see note below).

Surface note: the *Namespace types backing these exports are currently package-internal. deno doc --lint reports them as private-type-ref errors; making them public is planned for a future release. The runtime exports themselves are stable.

L0 primitives

Exported from the @netscript/fresh-ui/primitives sub-path. L0 stays small: prefer Preact intrinsic elements and platform attributes, using these helpers only where they encapsulate real behavior.

Primitive types

Generative UI renderer (@netscript/fresh-ui/ai/render-ui)

Exported from @netscript/fresh-ui/ai/render-ui. This module provides a safe, bounded generative-UI renderer that converts structured render_ui tool payloads into standard Preact DOM nodes.

Input contract: The renderer consumes input already validated by @netscript/ai/tools (RenderUiToolInput). It does not validate arbitrary model output; callers must parse and validate raw model payloads with @netscript/ai/tools before passing them to the renderer.

Allowed block categories

The renderer restricts markup generation to a curated 8-block allowlist across three categories (RENDER_UI_BLOCK_CATEGORIES):

Depth bounds and fallback reasons

To protect against deeply nested or malformed model payloads, rendering is bounded by maxDepth (defaults to RENDER_UI_MAX_DEPTH = 6). When a payload cannot be rendered safely, a styled fallback element is emitted with a specific RenderUiFallbackReason:

• 'max-depth': Payload nesting exceeded the configured maximum depth limit.
• 'unknown-type': Block type is outside the accepted 8-block allowlist.
• 'invalid-node': Node payload is malformed or unrenderable.

Renderer symbols

Renderer example

import { RenderUiSurface, renderUiPayload } from "@netscript/fresh-ui/ai/render-ui";

const payload = {
  component: "section",
  title: "System Performance",
  props: {
    children: [
      {
        type: "grid",
        props: {
          children: [
            {
              type: "metric",
              props: { label: "P99 Latency", value: "24 ms", detail: "healthy" },
            },
            {
              type: "metric",
              props: { label: "Error Rate", value: "0.01%", detail: "normal" },
            },
          ],
        },
      },
      {
        type: "table",
        title: "Active Services",
        props: {
          columns: [
            { key: "name", header: "Service" },
            { key: "status", header: "Status" },
          ],
          rows: [
            { name: "auth-service", status: "healthy" },
            { name: "payment-gateway", status: "healthy" },
          ],
        },
      },
    ],
  },
};

export function PerformanceWidget() {
  return <RenderUiSurface payload={payload} maxDepth={6} />;
}

Sub-path exports

The following 6 entrypoints are published as declared in the package export map:

Back to the reference overview.