structural-codes-viewer 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -1,18 +1,21 @@
 # structural-codes-viewer
 
-`structural-codes-viewer` è la reference UI React per consultare il corpus
-`structural-codes`. Il sottoprogetto contiene anche il consumer standalone
-locale usato per la revisione editoriale.
+`structural-codes-viewer` è il package React per consultare il corpus
+`structural-codes`. La stessa directory contiene l'applicazione standalone e
+la route ChatNTC self-hosted, che restano fuori dal tarball del package.
 
-- `structural-codes` contiene corpus, schema, provenance e relazioni canoniche;
-- `structural-codes-viewer` contiene UI React, client lazy degli artefatti e
-  generatore deterministico;
-- il viewer standalone Vinext/Vite è un consumer locale della stessa UI e può
-  aggiungere il PDF ufficiale tramite `OfficialPdfPanel`;
-- un futuro `ocfem-website` consumerà la stessa UI senza Vinext, Cloudflare o
-  PDF.js.
+## Boundary
 
-## Uso React
+- `structural-codes`: corpus, schema, provenance e helper non React;
+- `structural-codes-viewer`: componenti React, client lazy, generatore
+  artefatti e API ChatNTC condivise;
+- `viewer/app/` e `viewer/server/`: composizione standalone, route e adapter
+  provider non pubblicati nel package.
+
+React e ReactDOM sono peer dependency. Il package non dipende a runtime da
+Next/Vinext, `pdfjs-dist`, BGE-M3, adapter provider o file `.local`.
+
+## Viewer React
 
 ```tsx
 import { NormativeViewer } from "structural-codes-viewer";
@@ -23,80 +26,133 @@ export function Normativa() {
 }
 ```
 
-La modalità predefinita è `combined`: la NTC resta la struttura principale e
-la Circolare viene inserita soltanto tramite relazioni esplicite del corpus.
-Le relazioni `proposed` restano tracciate nei dati senza aggiungere etichette
-testuali alla lettura. Il client verifica `formatVersion`, schema e manifest; non usa
-la uguaglianza delle versioni SemVer per interpretare i dati.
-
-API intenzionale:
+Props principali:
 
 - `defaultMode`: `combined`, `ntc` o `circ`;
-- `dataBaseUrl`: directory degli artefatti lazy, default `/data/codes`;
-- `assetsBaseUrl`: directory delle figure, default `/assets`;
-- `auxiliaryPanel`: pannello opzionale o render prop locale;
-- `auxiliaryPanelDefaultVisible`: visibilità iniziale del pannello opzionale.
-
-La ricerca è sempre visibile ma carica `search-index.json` soltanto con almeno
-due caratteri. Manifest, indice documento, chunk e relazioni restano separati.
-Le figure sono lazy e il package shared non importa `pdfjs-dist`, non conosce
-`/api/source-pdf` e non dipende da Vinext o Cloudflare. React e ReactDOM sono
-peer dependencies React 19. Nell’indice della consultazione comparata ogni
-colonna segue la selezione corrente: capitolo → paragrafi → sottoparagrafi →
-dettagli. I capitoli entro la soglia di caricamento sono continui; quelli più
-grandi caricano il testo in continuità quando si seleziona il singolo paragrafo.
+- `dataBaseUrl`: artefatti lazy, default `/data/codes`;
+- `assetsBaseUrl`: figure, default `/assets`;
+- `auxiliaryPanel`: pannello opzionale o render prop;
+- `auxiliaryPanelDefaultVisible`, `auxiliaryPanelKeepMounted` e modalità
+  consentite del pannello.
 
-## Artefatti
+La vista combinata mantiene le NTC come struttura principale e inserisce la
+Circolare solo tramite relazioni esplicite. Ricerca, chunk, relazioni, figure e
+prefetch sono lazy; il package shared non importa PDF o route standalone.
 
-`npm run sync:corpus` mantiene il consumer locale aggiornato sotto
-`public/data/codes/`:
+## Artefatti
 
-```text
-manifest.json
-relations.json
-relation-diagnostics.json
-search-index.json
-ntc2018/index.json
-ntc2018/chunks/*.json
-circ2019/index.json
-circ2019/chunks/*.json
+```bash
+npm --prefix viewer run sync:corpus
 ```
 
-Il generatore condiviso legge soltanto i file pubblici del package
-`structural-codes`, è deterministico e non richiede un checkout sibling. La
-CLI inclusa nel package può materializzare gli stessi artefatti in un consumer:
+Il comando genera sotto `viewer/public/data/codes/` manifest, indici documento,
+chunk, relazioni, riferimenti e indice di ricerca. `viewer/public/` è ignorato
+da Git e rigenerabile dal corpus canonico.
+
+Un consumer può usare la CLI inclusa:
 
 ```bash
 npx structural-codes-viewer --source structural-codes \
   --output public/data/codes --assets public/assets
 ```
 
-Il comando non copia il corpus completo nel package viewer: usa il package
-`structural-codes` installato dal consumer come sorgente.
+Il package viewer non include il corpus completo: il generatore legge il
+package `structural-codes` installato nel consumer.
+
+## Export ChatNTC
+
+```ts
+import {
+  CHATNTC_DEFAULT_RETRIEVAL,
+  retrieveChatNTCEvidence,
+  validateChatNTCResponse,
+} from "structural-codes-viewer/chatntc";
+import { createViewerArtifactRepository } from
+  "structural-codes-viewer/chatntc/viewer-artifacts";
+import { ChatNTCPanel, type ChatTransport } from
+  "structural-codes-viewer/chatntc-ui";
+import { IndexedDbChatHistoryStore, type ChatHistoryStore } from
+  "structural-codes-viewer/chatntc-history";
+```
+
+Questi export sono shared/browser-safe. Route HTTP, provider secrets,
+`LocalChatTransport`, `LocalAIConfiguration` e impostazioni standalone non
+sono API del package.
 
-## Viewer standalone
+## Standalone senza ChatNTC
 
 ```bash
+npm ci
+npm run sync:corpus
 npm run dev
-npm run build
-npm test
 ```
 
-La route `/consultazione` usa `NormativeViewer` e compone il pannello PDF
-locale opzionale. PDF.js e il file PDF vengono caricati solo dopo l’azione
-esplicita “Apri PDF ufficiale”; il PDF non entra nel package shared.
+Il viewer funziona senza provider e senza ChatNTC. Il PDF ufficiale è un
+ausilio locale/debug e non entra nel build pubblico o nel package.
 
-## Package
+## ChatNTC self-hosted
 
-La prerelease non viene pubblicata da questo repository. Per una futura
-pubblicazione, dopo review:
+Dal root della repository:
 
 ```bash
-npm run build:library
-npm pack
-npm publish --access public
+npm run dev
 ```
 
-Il tarball contiene soltanto `package-dist/`, CSS, README e metadati del
-package; non contiene app standalone, worker Cloudflare, test, cache, corpus
-completo o `pdfjs-dist`.
+Il launcher abilita ChatNTC e vincola il server a `127.0.0.1`. In alternativa,
+copiando `viewer/.env.example` in `viewer/.env.local`, impostare:
+
+```dotenv
+CHATNTC_ENABLED=true
+CHATNTC_PROVIDER=deepseek
+CHATNTC_DEEPSEEK_API_KEY=
+CHATNTC_SEMANTIC_MODE=off
+```
+
+La chiave può restare vuota se l'utente usa la UI BYOK. Le chiavi environment
+rimangono server-side; quelle UI rimangono in memoria e viaggiano in un header
+stessa origine, mai nel body o nella history.
+
+Pipeline standard:
+
+```text
+query → lexical retrieval → structural expansion → Evidence Package
+      → LLM → Citation Validator → risposta verificata
+```
+
+Dettagli: [overview](../docs/chatntc-core.md),
+[self-hosting](../docs/chatntc-server.md),
+[BYOK](../docs/chatntc-byok.md) e
+[history](../docs/chatntc-history.md).
+
+## Semantic retrieval sperimentale
+
+`CHATNTC_SEMANTIC_MODE=off|shadow|on`; il default è `off`.
+
+- `off`: percorso lessicale standard, nessun indice o embedding;
+- `shadow`: calcolo semantic osservazionale, output lessicale invariato;
+- `on`: ranking fuso RRF con fallback lessicale.
+
+Gli adapter BGE-M3 HTTP e Ollama, i generatori indice e i benchmark sono
+strumenti opt-in. BGE-M3 non è una dipendenza obbligatoria del viewer o di
+ChatNTC. Vedere la
+[documentazione semantic](../docs/chatntc-semantic-index.md).
+
+## Sviluppo e verifica
+
+```bash
+npm ci
+npm run lint
+npm test
+npm run check
+npm run pack:verify
+npm run test:consumer
+```
+
+`check` costruisce app e libreria ed esegue test viewer, ChatNTC, history,
+semantic e boundary. `pack:verify` mostra il contenuto effettivo del tarball.
+`test:consumer` crea tarball reali di entrambi i package, li installa in una
+nuova app Next e verifica viewer, export ChatNTC runtime e tipi pubblici.
+
+Il tarball deve contenere soltanto `package-dist/`, README, licenza, notice e
+manifest. Sono vietati `app/`, `server/`, test, PDF, corpus completo, `.env`,
+cache, indici semantic e output standalone.

package/package-dist/CorpusContent.d.ts

@@ -1,16 +1,51 @@
-import type { AssetBundle, CorpusBlock, CorpusUnit } from "./corpusData";
+import type { AssetBundle, CorpusBlock, DocumentId, InlineSegment, CorpusUnit } from "./corpusData";
+export declare function leadingMathLabelEnd(inline: InlineSegment[]): number;
+export declare function hasOfficialListMarker(block: CorpusBlock): boolean;
+export declare function hasAlphaRatioListLayout(block: CorpusBlock, sourceUnitId?: string): boolean;
+export declare function hasInferredAlphaRatioListMarker(block: CorpusBlock, sourceUnitId?: string): boolean;
+export declare function hasAlphabeticListMarker(block: CorpusBlock): boolean;
+export declare function hasSimpleDashMarker(block: CorpusBlock): boolean;
+export declare function hasNoListMarker(block: CorpusBlock): boolean;
+export declare function listMarkerClass(block: CorpusBlock): "" | "list-item-with-bullet";
+export declare function listLevelClass(block: CorpusBlock): string;
+export declare function indentLevelClass(block: CorpusBlock): string;
+export declare function hasLeadingMath(block: CorpusBlock): boolean;
+export declare function hasAlignedListContinuation(block: CorpusBlock): boolean;
+export declare function hasLeadingEmphasisLabel(block: CorpusBlock): boolean;
+export declare function leadingLabelKind(block: CorpusBlock): "math" | "emphasis" | null;
+export type CorpusBlockGroup = {
+    kind: "label-list";
+    blocks: CorpusBlock[];
+} | {
+    kind: "block";
+    block: CorpusBlock;
+    index: number;
+};
+export declare function groupAlignedLabelBlocks(blocks: CorpusBlock[]): CorpusBlockGroup[];
+export declare function hasTrailingStrong(block: CorpusBlock): boolean;
+export declare function hasTrailingMath(block: CorpusBlock): boolean;
 export interface BlockContentProps {
     block: CorpusBlock;
     assets: AssetBundle | null;
-    showRaw?: boolean;
     assetsBaseUrl?: string;
+    aligned?: boolean;
+    sourceUnitId?: string;
+    sourceDocument?: DocumentId;
 }
-export declare function BlockContent({ block, assets, showRaw, assetsBaseUrl }: BlockContentProps): import("react/jsx-runtime").JSX.Element;
-export declare function isRepeatedUnitTitle(unit: CorpusUnit, block: CorpusUnit["blocks"][number]): boolean;
-export declare function UnitBlocks({ unit, assets, showRaw, compact, assetsBaseUrl }: {
-    unit: CorpusUnit;
-    assets: AssetBundle;
-    showRaw?: boolean;
-    compact?: boolean;
+type InlineSegments = InlineSegment[];
+interface ReferenceContext {
+    sourceUnitId: string;
+    sourceDocument: DocumentId;
+}
+export declare function renderInlineSegments(inline: InlineSegments, context?: ReferenceContext | null): import("react").ReactNode[];
+export declare function BlockContent({ block, assets, assetsBaseUrl, aligned, sourceUnitId, sourceDocument }: BlockContentProps): import("react/jsx-runtime").JSX.Element;
+export declare function AlignedLabelList({ blocks, assets, assetsBaseUrl, sourceUnitId, sourceDocument, renderAccessory }: {
+    blocks: CorpusBlock[];
+    assets: AssetBundle | null;
     assetsBaseUrl?: string;
+    sourceUnitId?: string;
+    sourceDocument?: DocumentId;
+    renderAccessory?: (block: CorpusBlock) => React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
+export declare function isRepeatedUnitTitle(unit: CorpusUnit, block: CorpusUnit["blocks"][number]): boolean;
+export {};