@brftech/filex-core 0.42.2 → 0.43.0

package/src/lib/surfaceConditions.ts

@@ -0,0 +1,156 @@
+/**
+ * surfaceConditions — `show_when` / `required_when`, as pure data.
+ *
+ * v3 §2.1: "a form may not present a contradiction". A field may declare
+ * that it exists only while another field holds a particular answer ("the
+ * name of the new file" appears only when the output IS a new file, and is
+ * then required), and the renderer — not the plugin — is what makes that
+ * true. The plugin cannot opt out of it and cannot get it half right.
+ *
+ * Three promises, all of them enforced here rather than in a component so
+ * the modal, the page, the public shell and the tests share one answer:
+ *
+ *   1. a field whose `show_when` does not hold is NOT drawn;
+ *   2. its value is dropped before the event is posted — it cannot arrive
+ *      at the plugin as a surprise, which is the whole point;
+ *   3. a field whose `required_when` holds behaves as `required`, so an
+ *      empty one blocks the submit instead of failing on the server.
+ *
+ * ⚠ Conditions CASCADE. A field can be shown by a field that is itself
+ * hidden, and a hidden controller answers nothing — so visibility is
+ * resolved to a fixed point rather than in one pass. Without it, hiding the
+ * middle of a three-field chain leaves the last one on screen asking about
+ * an answer nobody can see.
+ *
+ * ⚠ This is a CONVENIENCE for the person at the screen, not a security
+ * boundary — the host re-checks both rules when the job is submitted
+ * (v3 §2.1). Same relationship `applies` has with the server's re-check.
+ */
+import type { PluginCondition, PluginField, SurfaceNode } from '../types/Plugins';
+import { walkNodes } from './surfaceValues';
+
+/** Is there anything in this value at all? `false` and `0` count as answers. */
+export function hasAnswer(v: unknown): boolean {
+  if (v === undefined || v === null) return false;
+  if (typeof v === 'string') return v.trim() !== '';
+  if (Array.isArray(v)) return v.length > 0;
+  return true;
+}
+
+/** Every string a value holds — one for a scalar, several for a multi-select. */
+function valueStrings(v: unknown): string[] {
+  if (v === undefined || v === null) return [];
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  if (typeof v === 'boolean') return [v ? 'true' : 'false'];
+  return [String(v)];
+}
+
+/**
+ * Does `cond` hold against the surface's values?
+ *
+ * ⚠ An absent condition HOLDS. `show_when: null` is "always", which is what
+ * every field without one means, so the two paths do not diverge.
+ */
+export function conditionMet(cond: PluginCondition | null | undefined, values: Record<string, unknown>): boolean {
+  if (!cond || !cond.key) return true;
+  const raw = values?.[cond.key];
+  const wanted = cond.equals ?? [];
+  // No list of values: the condition is "that field has been answered".
+  if (!wanted.length) return hasAnswer(raw);
+  if (!hasAnswer(raw)) return false;
+  const have = valueStrings(raw);
+  return wanted.some((w) => have.includes(String(w)));
+}
+
+/** The fields of one form that the person may see, conditions cascaded. */
+export function visibleFields(
+  fields: PluginField[] | undefined,
+  values: Record<string, unknown>,
+): PluginField[] {
+  const all = (fields ?? []).filter((f) => f && f.key);
+  if (!all.length) return [];
+
+  // Fixed point: a field hidden in this pass stops answering for the next
+  // one, which can hide the field that depended on it, and so on. Bounded
+  // by the field count — a cycle simply settles.
+  let shown = all;
+  for (let pass = 0; pass <= all.length; pass++) {
+    const scope = scopedValues(all, shown, values);
+    const next = all.filter((f) => conditionMet(f.show_when, scope));
+    if (next.length === shown.length) return next;
+    shown = next;
+  }
+  return shown;
+}
+
+/** The values as the VISIBLE fields answer them — a hidden field answers nothing. */
+function scopedValues(
+  all: PluginField[],
+  shown: PluginField[],
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const visible = new Set(shown.map((f) => f.key));
+  const out: Record<string, unknown> = { ...values };
+  for (const f of all) if (!visible.has(f.key)) delete out[f.key];
+  return out;
+}
+
+/** Is this field required right now — declared, or by a `required_when` that holds? */
+export function fieldRequired(f: PluginField, values: Record<string, unknown>): boolean {
+  if (f.required === true) return true;
+  if (!f.required_when) return false;
+  return conditionMet(f.required_when, values);
+}
+
+/** Every `form` node's fields in a surface, flat. */
+export function formFields(nodes: SurfaceNode[] | undefined): PluginField[] {
+  const out: PluginField[] = [];
+  walkNodes(nodes, (n) => {
+    if (n.type !== 'form') return;
+    const fields = (n.props as { fields?: PluginField[] } | undefined)?.fields;
+    for (const f of fields ?? []) if (f && f.key) out.push(f);
+  });
+  return out;
+}
+
+/** The keys a surface is currently NOT showing (across every form on it). */
+export function hiddenKeys(nodes: SurfaceNode[] | undefined, values: Record<string, unknown>): string[] {
+  const all = formFields(nodes);
+  if (!all.length) return [];
+  const shown = new Set(visibleFields(all, values).map((f) => f.key));
+  return all.filter((f) => !shown.has(f.key)).map((f) => f.key);
+}
+
+/**
+ * The values to POST: everything the surface holds, minus what a hidden
+ * field was carrying.
+ *
+ * ⚠ Dropped, not blanked. `{name: ""}` is an answer ("call it nothing");
+ * the contract says the value "is dropped before the job runs", so the key
+ * must not be in the map at all.
+ */
+export function stripHiddenValues(
+  nodes: SurfaceNode[] | undefined,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const hidden = hiddenKeys(nodes, values);
+  if (!hidden.length) return { ...values };
+  const out = { ...values };
+  for (const k of hidden) delete out[k];
+  return out;
+}
+
+/**
+ * The visible-and-required fields a person has not answered. Empty means the
+ * submit may go; anything else is what to point at.
+ */
+export function missingRequired(
+  nodes: SurfaceNode[] | undefined,
+  values: Record<string, unknown>,
+): PluginField[] {
+  const all = formFields(nodes);
+  if (!all.length) return [];
+  const shown = visibleFields(all, values);
+  const scope = scopedValues(all, shown, values);
+  return shown.filter((f) => fieldRequired(f, scope) && !hasAnswer(scope[f.key]));
+}

package/src/lib/surfaceOpen.ts

@@ -0,0 +1,106 @@
+/**
+ * surfaceOpen — "go to this file, and start that screen on it".
+ *
+ * ⚠⚠ v3 §3.0. A surface runs on the file it was opened on, which meant an
+ * app's HOME screen could list documents and then do nothing when a row was
+ * clicked: there was nowhere for a screen to send anybody. `Surface.open`
+ * is that missing edge — the answer names a path and, optionally, one of the
+ * plugin's own screens, and the client goes there.
+ *
+ * ⚠ It is NOT a second navigation design. The address is the one a
+ * notification deep link already uses (`?select=<path>&app=<plugin>` plus
+ * `appAction=` or `appView=`, with the folder in the hash), because the two
+ * are the same request — "open this file with that screen on it" — and a
+ * second spelling of it would be a second thing to keep working.
+ *
+ * ⚠⚠ Trusted on arrival, and that is the SERVER's promise, not an omission
+ * here: the host checks the screen belongs to the plugin that answered, and
+ * the handler re-checks the path against the ASKING person's permissions,
+ * dropping the `open` rather than refusing the screen. So a client that
+ * re-derived its own permission check would be writing a second, weaker
+ * copy of a rule that has already been applied.
+ *
+ * ⚠ A public page never gets one — there is no explorer behind it — so a
+ * frame with no navigator simply ignores it (see `openHrefFor` returning '').
+ */
+import type { SurfaceOpenRequest } from '../types/Plugins';
+import { isPagePlacement, pluginPageUrl } from './pluginPage';
+
+/* ⚠ The shape itself lives in `types/Plugins`, with every other wire
+ * mirror. Declaring it here as well would be a second copy of a struct that
+ * only has one definition in `wire.go`. */
+export type { SurfaceOpenRequest };
+
+/** What the answer amounts to, once the frame knows where it is mounted. */
+export interface SurfaceOpenTarget {
+  href: string;
+  /**
+   * A `page` view is a whole screen with the document beside it and opens in
+   * its own tab — the same rule a `page` ACTION follows when it is clicked
+   * in the menu, so a plugin's screen behaves the same however it was
+   * reached.
+   */
+  newTab: boolean;
+}
+
+/** Is this a request the client can act on at all? */
+export function isOpenRequest(v: unknown): v is SurfaceOpenRequest {
+  if (!v || typeof v !== 'object') return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.path === 'string' && o.path.trim() !== '';
+}
+
+/**
+ * The folder part of an adapter-qualified path, as the explorer's hash wants
+ * it (`storage/dir/sub`), and the file itself for `?select=`.
+ */
+export function openHashFor(qualified: string): string {
+  const at = String(qualified ?? '').indexOf('://');
+  if (at <= 0) return '';
+  const storage = qualified.slice(0, at);
+  const rel = qualified.slice(at + 3).replace(/^\/+/, '');
+  const cut = rel.lastIndexOf('/');
+  const dir = cut > 0 ? rel.slice(0, cut) : '';
+  return dir ? `${storage}/${dir}` : storage;
+}
+
+export interface SurfaceOpenOptions {
+  /** The plugin that answered — the screen named is one of ITS own. */
+  plugin: string;
+  /** The prefix the SPA is served from (`/admin/`, `/drive/`). */
+  base?: string | null;
+  /**
+   * What placement the named view has, when the frame knows. `page` opens in
+   * a tab on the view's own address; anything else (and an unknown one) goes
+   * through the explorer, which is the frame that can open a dialog.
+   */
+  placementOf?: (id: string) => string | undefined;
+}
+
+/**
+ * Where this answer sends the person.
+ *
+ * `''` when there is nowhere to go: no path, or a frame with no explorer
+ * behind it. The caller draws its screen and does nothing, which is what a
+ * public page must do.
+ */
+export function openTargetFor(
+  req: SurfaceOpenRequest | null | undefined,
+  opts: SurfaceOpenOptions,
+): SurfaceOpenTarget {
+  if (!isOpenRequest(req) || !opts.plugin) return { href: '', newTab: false };
+  const base = String(opts.base ?? '').replace(/\/+$/, '');
+
+  // A `page` view is its own address, with the document beside it.
+  if (req.view && isPagePlacement(opts.placementOf?.(req.view))) {
+    return { href: pluginPageUrl(base, { plugin: opts.plugin, view: req.view, path: req.path }), newTab: true };
+  }
+
+  const q: string[] = [`select=${encodeURIComponent(req.path)}`, `app=${encodeURIComponent(opts.plugin)}`];
+  // ⚠ `action` OR `view`, never both — the contract says naming both is not
+  // a request, and sending both would leave the explorer to pick one.
+  if (req.action) q.push(`appAction=${encodeURIComponent(req.action)}`);
+  else if (req.view) q.push(`appView=${encodeURIComponent(req.view)}`);
+  const hash = openHashFor(req.path);
+  return { href: `${base}/explore?${q.join('&')}${hash ? `#${hash}` : ''}`, newTab: false };
+}

package/src/lib/surfaceSteps.ts

@@ -0,0 +1,68 @@
+/**
+ * surfaceSteps — "one step asks one thing", as pure data.
+ *
+ * v3 §2 rule 3: a multi-step surface has at most ONE primary button plus
+ * Back. The complaint behind it: a wizard step with eight fields and four
+ * buttons, where nothing on the screen said which button was the way
+ * forward — so the person picked one and found out afterwards.
+ *
+ * ⚠ Enforced by the RENDERER, not by each plugin. A plugin that marks three
+ * of its actions `primary: true` gets one primary (the first one it
+ * declared) and two ordinary buttons — it is not refused, and it does not
+ * get to draw three ways forward. Nothing is hidden: a button the plugin
+ * declared is a button the person can press, because silently dropping one
+ * would break a wizard in a way no test of ours would ever see.
+ *
+ * ⚠ "Back" is recognised by its ACTION ID, which is the only signal on the
+ * wire. `back`, `prev`, `previous` and the `step_back` / `go-back` spellings
+ * of them, case- and separator-insensitive. A step that calls its own
+ * backward action something else simply gets an ordinary button, which is
+ * what it would have had anyway.
+ */
+import type { SurfaceAction, SurfaceNode } from '../types/Plugins';
+import { walkNodes } from './surfaceValues';
+
+/** Does this surface have a `steps` node — i.e. is it a step of a walk? */
+export function hasSteps(nodes: SurfaceNode[] | undefined): boolean {
+  let found = false;
+  walkNodes(nodes, (n) => {
+    if (n.type === 'steps') found = true;
+  });
+  return found;
+}
+
+const BACK_IDS = new Set(['back', 'prev', 'previous', 'stepback', 'goback', 'prevstep', 'previousstep']);
+
+/** Is this the step's backward action? */
+export function isBackAction(a: Pick<SurfaceAction, 'id'>): boolean {
+  const id = String(a?.id ?? '')
+    .toLowerCase()
+    .replace(/[^a-z]/g, '');
+  return BACK_IDS.has(id);
+}
+
+/** A footer, arranged: Back on the left, the ordinary buttons, one primary last. */
+export interface StepFooter {
+  back: SurfaceAction | null;
+  /** In declaration order, minus Back and minus the one primary. */
+  others: SurfaceAction[];
+  primary: SurfaceAction | null;
+}
+
+/**
+ * Arrange a surface's actions for a step.
+ *
+ * `stepped` is what `hasSteps` said. On a surface that is NOT a step the
+ * plugin's own arrangement is left alone — a dialog with two equally weighted
+ * actions is a legitimate screen, and the rule is about walks.
+ */
+export function stepFooter(actions: SurfaceAction[] | undefined, stepped: boolean): StepFooter {
+  const list = (actions ?? []).filter((a) => a && a.id);
+  if (!stepped) {
+    return { back: null, others: list, primary: null };
+  }
+  const back = list.find(isBackAction) ?? null;
+  const rest = list.filter((a) => a !== back);
+  const primary = rest.find((a) => a.primary === true) ?? null;
+  return { back, others: rest.filter((a) => a !== primary), primary };
+}

package/src/lib/surfaceValues.ts

@@ -0,0 +1,191 @@
+/**
+ * surfaceValues — what a surface's nodes hold, as pure data.
+ *
+ * A plugin view is a conversation: every event the browser posts carries
+ * `data.values`, one entry per node that holds a value (contract: "a node
+ * with `id` that holds a value contributes `data.values[id]`"; a `form`'s
+ * fields are FLAT, keyed by field key, because that is what the plugin
+ * declared them as). The modal and the inspector section both post events,
+ * so the walk that seeds the map from a fresh surface lives here, once, and
+ * the two cannot seed differently.
+ *
+ * DOM-free on purpose: tests exercise the seeding and the field mapping
+ * without mounting anything.
+ */
+import type { StorageField } from '../types/Connections';
+import type {
+  FileChooserNodeProps,
+  FormNodeProps,
+  PdfFieldsNodeProps,
+  PeoplePickerNodeProps,
+  PluginField,
+  SurfaceNode,
+} from '../types/Plugins';
+import { fillValues, normalizeFields } from './pdfFields';
+import { labelOf } from './pluginLabel';
+
+/** Every `SurfaceNode` in the tree, depth first (rows are transparent). */
+export function walkNodes(nodes: SurfaceNode[] | undefined, visit: (n: SurfaceNode) => void): void {
+  for (const n of nodes ?? []) {
+    visit(n);
+    if (n.children?.length) walkNodes(n.children, visit);
+  }
+}
+
+/**
+ * The values a surface arrives with: `form.props.values` (flat, by field key,
+ * else each field's `default`), `people-picker.props.value`,
+ * `file-chooser.props.value`, a `pdf-fields` node's fields and an empty
+ * `signature-pad` under the node's id. Nodes without an id hold nothing the
+ * server can address, so they contribute nothing.
+ */
+export function initialValues(nodes: SurfaceNode[] | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  walkNodes(nodes, (n) => {
+    const p = (n.props ?? {}) as Record<string, unknown>;
+    if (n.type === 'form') {
+      const fp = p as unknown as FormNodeProps;
+      for (const f of fp.fields ?? []) {
+        if (!f?.key) continue;
+        const given = fp.values?.[f.key];
+        if (given !== undefined) out[f.key] = multiSafe(f, given);
+        else if (f.default !== undefined) out[f.key] = multiSafe(f, f.default);
+        else if (f.multi === true && f.type === 'select') out[f.key] = [];
+      }
+      return;
+    }
+    if (!n.id) return;
+    if (n.type === 'people-picker') {
+      const v = (p as PeoplePickerNodeProps).value;
+      out[n.id] = Array.isArray(v) ? v.filter((x) => x && typeof x.email === 'string') : [];
+    } else if (n.type === 'file-chooser') {
+      const v = (p as FileChooserNodeProps).value;
+      out[n.id] = typeof v === 'string' ? v : '';
+    } else if (n.type === 'pin-input') {
+      out[n.id] = '';
+    } else if (n.type === 'signature-pad') {
+      out[n.id] = null;
+    } else if (n.type === 'pdf-fields') {
+      // Edit mode sends the whole array back; fill mode only the signer's
+      // own filled fields (lib/pdfFields.fillValues) — seeded from what the
+      // surface already carries, so a re-opened screen keeps its values.
+      const pp = p as unknown as PdfFieldsNodeProps;
+      const fields = normalizeFields(pp.fields);
+      out[n.id] = pp.mode === 'fill' ? fillValues(fields, pp.signer) : fields;
+    }
+  });
+  return out;
+}
+
+/**
+ * A `multi` select always holds a LIST, whatever the plugin seeded it with.
+ *
+ * ⚠ A plugin that declares `multi: true` and sends `"pdf"` as the default is
+ * not wrong on the wire — the contract says the value is "a string (single)
+ * or a list of strings (multi)" — but a control that receives a string and
+ * emits an array would send a different SHAPE back than it was given, and
+ * the plugin would have to handle both. Normalised once, on the way in.
+ */
+function multiSafe(f: PluginField, v: unknown): unknown {
+  if (f.multi !== true || f.type !== 'select') return v;
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  return v === undefined || v === null || v === '' ? [] : [String(v)];
+}
+
+const FIELD_TYPES = new Set(['string', 'int', 'bool', 'password', 'select']);
+
+/**
+ * Is this `bool` a DECISION the person must read, or an on/off switch?
+ *
+ * The wire HAS a word for it now — `wire.Field.Style` (`switch` | `choice`)
+ * — so the plugin's own answer comes first and the guess only runs when the
+ * plugin said nothing:
+ *
+ *   - `style: "choice"` → two buttons, `style: "switch"` → the toggle. Said
+ *     outright, it beats every heuristic below, including `options`: a
+ *     plugin that names its two labels and still wants a switch gets one.
+ *   - the plugin NAMED the two answers (`options`), which nobody does for a
+ *     switch: "Keep the original / Replace it" is a decision;
+ *   - the field is `required`, i.e. the form will not go until it is
+ *     answered — and an unticked checkbox is indistinguishable from a
+ *     question nobody has reached yet.
+ *
+ * Everything else stays the checkbox a settings toggle wants. ⚠ That last
+ * line is a GUESS, and a wrong one for a question like "should this
+ * installation add time stamps?" — which is why the contract asks a plugin
+ * to say `style` when the answer matters, rather than this file getting
+ * cleverer about bools it was told nothing about.
+ *
+ * ⚠ `select` never asks: it is buttons whatever `style` says (`storageFieldOf`
+ * below), because a surface has no dropdown to fall back to.
+ */
+function boolIsDecision(f: PluginField): boolean {
+  const style = String(f.style ?? '').toLowerCase();
+  if (style === 'choice') return true;
+  if (style === 'switch') return false;
+  if ((f.options ?? []).length > 0) return true;
+  return f.required === true;
+}
+
+/**
+ * A plugin's field as the shared field renderer (`components/StorageFields`)
+ * reads it. `i18n_key` is empty on purpose: the renderer asks the catalogue
+ * first and falls back to `label` when the key is unknown, and `''` is
+ * unknown — so a plugin's own words (already read in the viewer's language)
+ * are what show. `secret` fields are drawn masked whatever their type says.
+ *
+ * ⚠⚠ v3: `choice` is set HERE, for every plugin `select`, and `advanced` is
+ * not carried at all. Those two lines are the whole of "no dropdowns and no
+ * hidden sections in a surface" — applied to the declaration on its way in,
+ * so the renderer stays one renderer and no plugin can opt out of the rule
+ * by drawing its own control.
+ *
+ * ⚠⚠ This is the ONLY mapper. Every screen that turns a plugin's `Field`
+ * into something drawable goes through it: the surface form
+ * (`components/plugin/nodes/SurfaceForm.vue`) AND the admin's own app
+ * settings screen (web `components/plugins/AppPluginDetail.vue`). There used
+ * to be a second one in the admin (`api/appPlugins.fieldToStorageField`); it
+ * never set `choice`, dropped `multi` and carried an `advanced` the contract
+ * had already deleted, so one manifest field meant two different things on
+ * two screens. A new surface adds a CALLER here, never a mapper of its own.
+ */
+export function storageFieldOf(f: PluginField, locale: string): StorageField {
+  const type = f.secret ? 'password' : FIELD_TYPES.has(String(f.type)) ? f.type : 'string';
+  return {
+    key: f.key,
+    type: type as StorageField['type'],
+    label: labelOf(f.label, locale) || f.key,
+    help: labelOf(f.help, locale) || undefined,
+    i18n_key: '',
+    required: f.required === true,
+    secret: f.secret === true,
+    default: f.default,
+    placeholder: labelOf(f.placeholder, locale) || undefined,
+    options: (f.options ?? []).map((o) => ({ value: String(o.value), label: labelOf(o.label, locale) || String(o.value) })),
+    min: f.min,
+    max: f.max,
+    monospace: f.monospace === true,
+    // ⚠⚠ `text` IS the contract's long text (wire.Field: "string | password
+    // | int | bool | select | text"), and the field renderer draws a textarea
+    // only on `multiline`. Nothing mapped the two, so every long field a
+    // plugin asked for arrived as a one-line box — including the signing
+    // app's list of signers, under a help line that says "one per line".
+    multiline: f.multiline === true || String(f.type) === 'text',
+    choice: type === 'select' || (type === 'bool' && boolIsDecision(f)),
+    multi: f.multi === true,
+  };
+}
+
+/** A `pin-input`'s length: 4..8, default 6 — the contract's bounds. */
+export function pinLength(raw: unknown): number {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 6;
+  return Math.min(8, Math.max(4, Math.trunc(n)));
+}
+
+/** Good enough for "this looks like an address" — the server validates. */
+export function looksLikeEmail(s: string): boolean {
+  const v = s.trim();
+  const at = v.indexOf('@');
+  return at > 0 && at < v.length - 1 && !/\s/.test(v) && v.indexOf('@', at + 1) === -1;
+}

package/src/lib/symlink.ts

@@ -0,0 +1,150 @@
+/**
+ * symlink — a link the server will NOT follow, said in words.
+ *
+ * Issue #34: a symlink to a directory inside a `local` storage root listed as
+ * a 0-byte file that would not open. The backend half of the answer landed
+ * first: a link whose target is INSIDE the root is now followed, so it comes
+ * back as the directory it is and opens normally — nothing here is involved in
+ * that case, and nothing here should be. What is left is the other half, which
+ * is the half the reporter actually complained about: a link the server
+ * refuses to follow still arrives looking like an ordinary file, and clicking
+ * it does nothing anybody can explain.
+ *
+ * ⚠⚠ THE WIRE, AS MEASURED — read this before changing anything below.
+ * The driver decides a link's fate in `local.describeLink` and records it as
+ * `storage.MetaLinkState` (`followed` / `outside_root` / `broken` /
+ * `unresolved`). What reaches the browser is LESS than that, and it is less in
+ * two different ways:
+ *
+ *   1. `followed` never arrives. `handlers/manager.go` attaches the keys only
+ *      when `o.Kind == storage.KindSymlink`, and a followed link has already
+ *      become `KindDirectory`/`KindFile` by then. That is correct — a followed
+ *      link IS its target and needs no explaining — so `symlink: true` on the
+ *      wire always means "this one will not open".
+ *   2. `link_state` is the EXCEPTION, not the rule. Two projectors build
+ *      listing rows:
+ *        • `projectFileNodes` (manager.go:1412) — the DB cache, i.e. the
+ *          normal, steady-state listing. It emits `symlink: true` and NOTHING
+ *          ELSE, because `model.Node` has no column for the state: the reason
+ *          is a property of the link right now, and the catalogue stores what
+ *          was seen at scan time.
+ *        • `projectDriverObjects` (manager.go:826) — the cold-cache / pre-sync
+ *          fallback, which reads the driver directly and therefore DOES carry
+ *          `link_state`.
+ *      So `symlink: true` with no `link_state` is the COMMON case, not an edge
+ *      one, and `'unknown'` below is a first-class state with wording of its
+ *      own. A design that only handled the three named states would leave the
+ *      reporter's own screen — a warm cache — exactly as broken as before.
+ *
+ * `link_target` (the resolved path a followed directory link carries for the
+ * walk's cycle guard) is never serialised at all. It is a server-side identity
+ * and no surface should grow a dependency on it.
+ *
+ * ⚠ The wire `type` stays inside the closed `'file' | 'dir'` union: widening
+ * it would be a breaking change for every embedder of `@brftech/filex`, so an
+ * unfollowable link is reported as a file and FLAGGED. Everything here reads
+ * the flag; nothing here looks at `type`.
+ *
+ * ⚠ ONE reader, for the same reason `lib/appLock` is one reader: the badge on
+ * the row, the line in the details panel and the toast after a refused open
+ * all take their words from here. A second phrasing is how a badge saying
+ * "Outside" ends up beside a toast saying "Error".
+ */
+import type { FileNode } from '../types/FileNode';
+
+/**
+ * Why a link will not open.
+ *
+ * The first three are `storage.LinkOutsideRoot` / `LinkBroken` /
+ * `LinkUnresolved`. `unknown` is ours: the row says it is a link and the
+ * server did not say why — the warm-cache listing (see the note above), or a
+ * server newer than this client that named a state we have never heard of.
+ * Both deserve the honest general sentence rather than silence.
+ */
+export type LinkState = 'outside_root' | 'broken' | 'unresolved' | 'unknown';
+
+const NAMED: readonly string[] = ['outside_root', 'broken', 'unresolved'];
+
+/**
+ * The state of a row the server will not follow, or `null` for every ordinary
+ * row — including a link it DID follow, which arrives as its target and is not
+ * a link as far as anyone using it is concerned.
+ */
+export function linkStateOf(node: Pick<FileNode, 'symlink' | 'link_state'> | null | undefined): LinkState | null {
+  if (!node || node.symlink !== true) return null;
+  const s = node.link_state;
+  return typeof s === 'string' && NAMED.includes(s) ? (s as LinkState) : 'unknown';
+}
+
+/** What `linkWords` needs from the caller's locale. */
+export interface LinkWordsHost {
+  t: (key: string, vars?: Record<string, string | number>) => string;
+}
+
+/** The short word on the row, and the sentence behind it. */
+export interface LinkWords {
+  state: LinkState;
+  /** The badge's visible text — two words at most; the row is narrow. */
+  badge: string;
+  /**
+   * What it is, why it will not open, and who can change that — in a sentence,
+   * because "Outside" on its own is a second riddle rather than an answer.
+   */
+  why: string;
+}
+
+/**
+ * The words for a state.
+ *
+ * ⚠ BROKEN IS NOT OUTSIDE-OF-ROOT and must never read as if it were. Telling
+ * somebody an administrator can allow a link whose target has been deleted
+ * sends them to a settings screen that will not help, and leaves the real
+ * repair — fix or remove the link on the server — unsaid.
+ *
+ * ⚠ Literal `t('…')` keys on purpose: `web/tests/i18n/coreKeysUsed.test.ts`
+ * scans the source for them and skips anything computed, so a table built with
+ * `t('symlink.badge.' + state)` would take these eight strings outside the only
+ * check that notices a key nobody ever added to the catalogues.
+ */
+export function linkWords(state: LinkState | null, host: LinkWordsHost): LinkWords | null {
+  switch (state) {
+    case 'outside_root':
+      return { state, badge: host.t('symlink.badge.outside_root'), why: host.t('symlink.why.outside_root') };
+    case 'broken':
+      return { state, badge: host.t('symlink.badge.broken'), why: host.t('symlink.why.broken') };
+    case 'unresolved':
+      return { state, badge: host.t('symlink.badge.unresolved'), why: host.t('symlink.why.unresolved') };
+    case 'unknown':
+      return { state, badge: host.t('symlink.badge.unknown'), why: host.t('symlink.why.unknown') };
+    default:
+      return null;
+  }
+}
+
+/** The one call a view makes: the words for this row, or `null`. */
+export function linkWordsFor(
+  node: Pick<FileNode, 'symlink' | 'link_state'> | null | undefined,
+  host: LinkWordsHost,
+): LinkWords | null {
+  return linkWords(linkStateOf(node), host);
+}
+
+/**
+ * Is this row one no surface may try to open?
+ *
+ * ⚠⚠ THE DECISION, WRITTEN DOWN. An unfollowable link is refused by the
+ * CLIENT, before any request, and the refusal is spoken (a toast carrying
+ * `why`). The two alternatives were both live bugs:
+ *
+ *   • doing nothing is issue #34 itself — the row that "just does not open";
+ *   • letting the request go is barely better, because the driver answers with
+ *     a containment error that surfaces as a generic failure and reads like a
+ *     server fault rather than a deliberate, configurable boundary.
+ *
+ * Refusing here costs nothing the person could have had: the server would
+ * refuse it too, and only this side knows the sentence that says why and names
+ * the setting that changes it.
+ */
+export function isUnopenableLink(node: Pick<FileNode, 'symlink' | 'link_state'> | null | undefined): boolean {
+  return linkStateOf(node) !== null;
+}