@flood-md/agent 0.2.9 → 0.2.10

package/lib/index.mjs

@@ -0,0 +1,144 @@
+import { readFile, lstat, realpath, open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, resolve, relative, isAbsolute, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const KINDS = new Set(['guide', 'workflow', 'reference', 'component', 'recipe', 'token']);
+const ID = /^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9.-]*$/;
+const MAX_CATALOG_BYTES = 8 * 1024 * 1024;
+const MAX_MATERIAL_BYTES = 1024 * 1024;
+const PAGE_BYTES = 16 * 1024;
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = (code, message) => { const error = new Error(message); error.code = code; throw error; };
+const inside = (root, path) => { const r = relative(root, path); return r === '' || (r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r)); };
+const safePath = path => typeof path === 'string' && /^[a-zA-Z0-9._/-]+$/.test(path) && !path.startsWith('/') && !path.split('/').some(part => !part || part === '.' || part === '..');
+const text = (value, limit) => typeof value === 'string' && value.trim().length > 0 && value.length <= limit;
+
+/** Validate the data contract without loading material bodies or executing instructions. */
+export function validateKnowledgeCatalog(catalog) {
+  if (catalog?.schemaVersion !== 1 || !/^\d+\.\d+\.\d+$/.test(catalog.version ?? '') || !Array.isArray(catalog.groups) || !catalog.groups.length || catalog.groups.length > 16 || !Array.isArray(catalog.materials) || !catalog.materials.length || !Array.isArray(catalog.capabilities) || catalog.capabilities.length > 32) fail('INVALID_CATALOG', 'Unsupported or incomplete Flood knowledge catalog.');
+  const groups = new Set(), ids = new Set(), files = new Set();
+  for (const group of catalog.groups) {
+    if (!/^[a-z][a-z0-9-]*$/.test(group.id ?? '') || groups.has(group.id) || !text(group.name, 128) || !text(group.description, 256)) fail('INVALID_CATALOG', 'Invalid or duplicate knowledge group.');
+    groups.add(group.id);
+  }
+  let previous = '';
+  for (const item of catalog.materials) {
+    if (!ID.test(item.id ?? '') || ids.has(item.id) || item.id <= previous || !KINDS.has(item.kind) || !item.id.startsWith(item.kind + ':') || !text(item.name, 128) || !text(item.description, 1024) || !safePath(item.file) || files.has(item.file) || !/^[a-f0-9]{64}$/.test(item.sha256 ?? '') || !Number.isSafeInteger(item.bytes) || item.bytes < 1 || item.bytes > MAX_MATERIAL_BYTES || !Array.isArray(item.groups) || !item.groups.length || item.groups.length > 8 || new Set(item.groups).size !== item.groups.length || item.groups.some(group => !groups.has(group)) || !Array.isArray(item.links) || !Array.isArray(item.requires) || item.status !== 'available') fail('INVALID_CATALOG', 'Invalid, unsorted or duplicate knowledge material.');
+    if (item.installedTarget !== undefined && (!safePath(item.installedTarget) || !(item.installedTarget.startsWith('flood/') || item.installedTarget.startsWith('.agents/skills/flood-ui/')))) fail('INVALID_CATALOG', 'Invalid owned guide target.');
+    if (item.requires.length > 16 || item.links.length > 256 || new Set(item.requires).size !== item.requires.length || new Set(item.links).size !== item.links.length) fail('INVALID_CATALOG', 'Knowledge relationships exceed their per-material budget or contain duplicates.');
+    ids.add(item.id); files.add(item.file); previous = item.id;
+  }
+  const byId = new Map(catalog.materials.map(item => [item.id, item]));
+  for (const item of catalog.materials) for (const id of [...item.links, ...item.requires]) if (!ids.has(id)) fail('INVALID_CATALOG', `Unresolved knowledge relationship: ${id}`);
+  const visiting = new Set(), depths = new Map();
+  const visit = id => {
+    if (visiting.has(id)) fail('INVALID_CATALOG', 'Knowledge prerequisite cycle.');
+    if (depths.has(id)) return depths.get(id);
+    if (visiting.size >= 32) fail('INVALID_CATALOG', 'Knowledge prerequisites exceed the supported depth.');
+    visiting.add(id);
+    let depth = 1;
+    for (const dependency of byId.get(id).requires) depth = Math.max(depth, 1 + visit(dependency));
+    visiting.delete(id);
+    if (depth > 32) fail('INVALID_CATALOG', 'Knowledge prerequisites exceed the supported depth.');
+    depths.set(id, depth); return depth;
+  };
+  for (const id of ids) visit(id);
+  const capabilities = new Set();
+  for (const item of catalog.capabilities) {
+    if (!/^[a-z][a-z0-9-]*$/.test(item.id ?? '') || capabilities.has(item.id) || !['available', 'not-provided'].includes(item.status) || !text(item.description, 256) || !Array.isArray(item.materials) || item.materials.length > 16 || item.materials.some(id => !ids.has(id)) || (item.status === 'available' && !item.materials.length) || (item.status === 'not-provided' && item.materials.length)) fail('INVALID_CATALOG', 'Invalid knowledge capability declaration.');
+    capabilities.add(item.id);
+  }
+  return catalog;
+}
+
+async function readRegular(root, path, maxBytes) {
+  if (!safePath(path)) fail('INVALID_PATH', 'Knowledge paths must come from the package catalog.');
+  const base = await realpath(root);
+  let current = base;
+  for (const part of path.split('/')) {
+    current = resolve(current, part);
+    const stat = await lstat(current).catch(() => fail('MISSING_MATERIAL', `Missing knowledge file: ${path}`));
+    if (stat.isSymbolicLink()) fail('INVALID_PATH', 'Refusing a linked knowledge file or directory.');
+  }
+  if (!inside(base, await realpath(current))) fail('INVALID_PATH', 'Knowledge file left its package root.');
+  const handle = await open(current, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > maxBytes) fail('INVALID_MATERIAL', 'Knowledge file is not a bounded regular file.');
+    const bytes = await handle.readFile();
+    if (bytes.length > maxBytes) fail('INVALID_MATERIAL', 'Knowledge file exceeds its read budget.');
+    return bytes;
+  } finally { await handle.close(); }
+}
+
+const decode = bytes => { try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('INVALID_MATERIAL', 'Knowledge must be valid UTF-8.'); } };
+const summary = ({id, kind, name, description, groups, status, links, requires}) => ({id, kind, name, description, groups: [...groups], status, relatedCount: links.length, requires: [...requires]});
+
+/** A provider-neutral, read-only reader. A fresh catalog is checked on every operation. */
+export function createKnowledgeReader({root = DEFAULT_ROOT} = {}) {
+  async function load() {
+    const bytes = await readRegular(root, 'dist/catalog.json', MAX_CATALOG_BYTES);
+    let catalog;
+    try { catalog = JSON.parse(decode(bytes)); } catch (error) { if (error.code) throw error; fail('INVALID_CATALOG', 'Malformed Flood knowledge catalog.'); }
+    validateKnowledgeCatalog(catalog);
+    const pkg = JSON.parse(decode(await readRegular(root, 'package.json', 64 * 1024)));
+    if (pkg.name !== '@flood-md/agent' || pkg.version !== catalog.version) fail('VERSION_MISMATCH', 'Agent package and knowledge catalog versions differ.');
+    return {catalog, fingerprint: digest(bytes)};
+  }
+  return {
+    async info() {
+      const {catalog, fingerprint} = await load();
+      return {schemaVersion: 1, version: catalog.version, fingerprint, materialCount: catalog.materials.length,
+        groups: catalog.groups.map(group => ({...group, count: catalog.materials.filter(item => item.groups.includes(group.id)).length})),
+        kinds: [...KINDS].map(kind => ({kind, count: catalog.materials.filter(item => item.kind === kind).length})),
+        capabilities: structuredClone(catalog.capabilities)};
+    },
+    async list({kind, group, search = '', limit = 12, cursor} = {}) {
+      if ((kind !== undefined && !KINDS.has(kind)) || !Number.isSafeInteger(limit) || limit < 1 || limit > 50 || typeof search !== 'string' || search.length > 160) fail('INVALID_QUERY', 'Invalid catalog kind, limit or search.');
+      const {catalog, fingerprint} = await load();
+      if (group !== undefined && !catalog.groups.some(item => item.id === group)) fail('INVALID_QUERY', 'Unknown knowledge group.');
+      const query = {kind: kind ?? null, group: group ?? null, search: search.trim().toLowerCase()};
+      const queryHash = digest(JSON.stringify(query));
+      let offset = 0;
+      if (cursor !== undefined) {
+        let state;
+        try { if (typeof cursor !== 'string' || cursor.length > 1024 || !/^[A-Za-z0-9_-]+$/.test(cursor)) throw Error(); state = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); } catch { fail('INVALID_CURSOR', 'Malformed knowledge cursor.'); }
+        if (state.fingerprint !== fingerprint || state.query !== queryHash || !Number.isSafeInteger(state.offset) || state.offset < 1) fail('STALE_CURSOR', 'Catalog or query changed; start a fresh catalog page.');
+        offset = state.offset;
+      }
+      const matches = catalog.materials.filter(item => (!kind || item.kind === kind) && (!group || item.groups.includes(group)) && (!query.search || `${item.id} ${item.name} ${item.description}`.toLowerCase().includes(query.search)));
+      if (offset > matches.length) fail('INVALID_CURSOR', 'Knowledge cursor is outside the result set.');
+      const page = [];
+      const response = () => {
+        const next = offset + page.length;
+        return {schemaVersion: 1, version: catalog.version, fingerprint, query, total: matches.length, items: page,
+          truncated: next < matches.length, nextCursor: next < matches.length ? Buffer.from(JSON.stringify({fingerprint, query: queryHash, offset: next})).toString('base64url') : null};
+      };
+      for (const item of matches.slice(offset, offset + limit)) {
+        page.push(summary(item));
+        if (Buffer.byteLength(JSON.stringify(response())) > PAGE_BYTES) { page.pop(); break; }
+      }
+      if (offset < matches.length && !page.length) fail('INVALID_CATALOG', 'A catalog entry exceeds the discovery budget.');
+      return response();
+    },
+    async read(id, {offset = 0, length = 10000, linksOffset = 0} = {}) {
+      if (!ID.test(id ?? '') || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 1 || length > 40000 || !Number.isSafeInteger(linksOffset) || linksOffset < 0) fail('INVALID_QUERY', 'Use a known material ID and a bounded character range.');
+      const {catalog, fingerprint} = await load();
+      const item = catalog.materials.find(item => item.id === id);
+      if (!item) fail('UNKNOWN_MATERIAL', `Unknown installed knowledge material: ${id}`);
+      if (linksOffset > item.links.length) fail('INVALID_QUERY', 'Link offset is outside the material.');
+      const bytes = await readRegular(root, item.file, MAX_MATERIAL_BYTES);
+      if (bytes.length !== item.bytes || digest(bytes) !== item.sha256) fail('INTEGRITY_MISMATCH', 'Knowledge content differs from the versioned catalog.');
+      const chars = Array.from(decode(bytes));
+      if (offset > chars.length) fail('INVALID_QUERY', 'Read offset is outside the material.');
+      const end = Math.min(chars.length, offset + length);
+      return {schemaVersion: 1, version: catalog.version, fingerprint, ...summary(item), source: 'package',
+        sha256: item.sha256, installedTarget: item.installedTarget ?? null, links: item.links.slice(linksOffset, linksOffset + 32),
+        linksOffset, nextLinksOffset: linksOffset + 32 < item.links.length ? linksOffset + 32 : null,
+        text: chars.slice(offset, end).join(''), offset, totalCharacters: chars.length,
+        truncated: end < chars.length, nextOffset: end < chars.length ? end : null};
+    },
+  };
+}

package/lib/inspect.d.ts

@@ -0,0 +1,12 @@
+export interface InspectionTarget {tag:string;id:string|null;className:string;label:string;}
+export interface InspectionIssue {id:'icons.text-glyph'|'icons.unslotted-svg'|'table.mixed-row-centre'|'table.word-fragment'|'copy.action-echo'|'copy.unowned-support'|'forms.track-drift'|'forms.content-track-drift'|'layout.page-overflow';target:InspectionTarget;related?:InspectionTarget;message:string;offset?:number;word?:string;}
+export interface RenderedUIInspection {
+  schemaVersion:1;issues:InspectionIssue[];copy:InspectionTarget[];
+  fields:(InspectionTarget&{x:number;y:number;width:number;height:number})[];
+  truncated:boolean;notChecked:string[];
+}
+/** Invoke inside a browser document, e.g. page.evaluate(inspectRenderedUI). No mutation or network calls. */
+export declare function inspectRenderedUI(options?:{rootSelector?:string;maxElements?:number}):RenderedUIInspection;
+export interface SourceUIIssue {id:'composition.native-dialog'|'composition.native-control'|'composition.layout-owner'|'composition.scaled-minimum';line:number;column:number;excerpt:string;owner:string;message:string;}
+/** Text observations, not an AST or conformance check. No file access, execution or network. */
+export declare function inspectSourceUI(source:string,options?:{format?:'jsx'|'css';maxFindings?:number}):{schemaVersion:1;issues:SourceUIIssue[];truncated:boolean;notChecked:string[]};

package/lib/inspect.mjs

@@ -0,0 +1,187 @@
+/** Optional text observations for host-owned JSX/CSS; no parsing or execution. */
+export function inspectSourceUI(source,options={}) {
+  if(typeof source!=='string'||source.length>500000)throw new Error('Source must be a string of at most 500000 UTF-16 units');
+  const limit=options.maxFindings??50,format=options.format??'jsx';
+  if(!Number.isSafeInteger(limit)||limit<1||limit>500)throw new Error('maxFindings must be an integer from 1 to 500');
+  if(!['jsx','css'].includes(format))throw new Error('format must be jsx or css');
+  const issues=[];let truncated=false;
+  const record=(match,id,owner,message)=>{
+    if(issues.length>=limit){truncated=true;return;}
+    const offset=match.index+match[0].length-match[0].trimStart().length;
+    const prefix=source.slice(0,offset),line=prefix.split('\n').length,column=offset-prefix.lastIndexOf('\n');
+    issues.push({id,line,column,excerpt:match[0].trimStart().slice(0,180),owner,message});
+  };
+  if(format==='jsx'){
+    for(const match of source.matchAll(/\b(?:window|globalThis)\.(confirm|alert|prompt)\s*\(/g))record(match,'composition.native-dialog',match[1]==='confirm'?'AlertDialog':match[1]==='prompt'?'Dialog':'Alert','Native browser dialog candidate. Review the actual call and use the installed Flood owner unless native UI is explicitly required.');
+    for(const match of source.matchAll(/<(select|button)\b|<input\b[^>]*\btype\s*=\s*["'](date|time|checkbox|radio|range)["']/g)){
+      const role=match[1]||match[2],owner={select:'Select',button:'Button',date:'DatePicker',time:'TimeField',checkbox:'Checkbox',radio:'Radio',range:'Slider'}[role];
+      record(match,'composition.native-control',owner,'Raw control candidate. Review whether an existing Flood component owns this role; native form/table structure and deliberate documented adapters are separate cases.');
+    }
+  } else {
+    for(const match of source.matchAll(/([^{}]+)\{[^{}]*\bdisplay\s*:\s*(grid|flex)\b/g)){
+      if(match[1].trim().startsWith('.flood-'))continue;
+      record(match,'composition.layout-owner',match[2]==='grid'?'Grid':'Stack / Inline','Custom layout candidate. Shared form tracks and repeated layout roles should use Flood owners. A semantic host shell can legitimately own positioning; record the actual reason.');
+    }
+    for(const match of source.matchAll(/\bmin-(?:width|inline-size)\s*:\s*(\d*\.?\d+)rem\b/g)){
+      if(Number(match[1])>0)record(match,'composition.scaled-minimum','Container / local ScrollArea','Rem-based minimum width candidate. If applied to the whole host, it can force page overflow when text grows. Dense table minima can be legitimate inside a local scroll owner; inspect the actual selector and enlarged desktop result.');
+    }
+  }
+  return {schemaVersion:1,issues,truncated,notChecked:['Text matching is not parsing: comments, strings and examples can match; aliases, dynamic types and indirect calls can be missed. Review source context.','This function reads only the supplied text. It does not execute it, open files or inspect imports, component capability, rendered layout or editorial necessity.']};
+}
+
+/** Read-only DOM observations. Pass this self-contained function to page.evaluate. */
+export function inspectRenderedUI(options = {}) {
+  if (typeof document === 'undefined') throw new Error('inspectRenderedUI must run in the rendered browser document');
+  const root = options.rootSelector ? document.querySelector(options.rootSelector) : document;
+  if (!root) throw new Error('Flood inspection root was not found');
+  const limit = options.maxElements ?? 500;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 2000) throw new Error('maxElements must be an integer from 1 to 2000');
+  const issues = [], copy = [], fields = [];
+  const visible = element => {
+    const style = getComputedStyle(element), box = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && box.width > 0 && box.height > 0;
+  };
+  const label = element => (element.getAttribute('aria-label') || element.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 180);
+  const target = element => ({tag:element.tagName.toLowerCase(), id:element.id || null, className:element.getAttribute('class') || '', label:label(element)});
+  let truncated = false;
+  const addIssue = finding => { if (issues.length < limit) issues.push(finding); else truncated = true; };
+  const select = selector => {
+    const matches = [...root.querySelectorAll(selector)].filter(visible);
+    if(matches.length > limit) truncated = true;
+    return matches.slice(0, limit);
+  };
+  if(root===document&&document.documentElement.scrollWidth>innerWidth+1)addIssue({id:'layout.page-overflow',target:{tag:'html',id:document.documentElement.id||null,className:document.documentElement.getAttribute('class')||'',label:'Document'},offset:document.documentElement.scrollWidth-innerWidth,message:'The document extends beyond the viewport. Review the actual overflow owner at this text size; dense content can scroll locally. Hiding page overflow does not repair the layout.'});
+  for (const button of select('button.flood-button, button.flood-icon-button')) {
+    // Text is inspected outside real icon slots, SVGs and visually hidden names.
+    const walker = document.createTreeWalker(button, NodeFilter.SHOW_TEXT);
+    const parts = []; let node;
+    while ((node = walker.nextNode())) {
+      if (!node.parentElement?.closest('.flood-icon,svg,.flood-visually-hidden,[aria-hidden="true"]')) parts.push(node.textContent);
+    }
+    const text = parts.join('').trim();
+    if (/^[+＋×✕✖↗→←✓✔☰](?:\s|$)|(?:\s)[+＋×✕✖↗→←✓✔☰]$/u.test(text)) {
+      addIssue({id:'icons.text-glyph', target:target(button), message:'Possible action icon encoded as font text; review whether IconSlot with explicit artwork is required.'});
+    }
+    for (const svg of button.querySelectorAll('svg')) {
+      if (!svg.closest('.flood-icon,.flood-loading,.flood-spinner')) addIssue({id:'icons.unslotted-svg',target:target(button),message:'Action SVG has no Flood IconSlot owner; inspect sizing and accessible decoration.'});
+    }
+  }
+  for (const row of select('.flood-table tbody tr')) {
+    const controls = [...row.querySelectorAll('input:not([type="hidden"]),textarea,select')].filter(visible);
+    const actions = [...row.querySelectorAll('button,a.flood-link--button')].filter(visible);
+    if (!controls.length && !actions.length) continue;
+    const centres = controls.map(control=>{const r=control.getBoundingClientRect();return r.y+r.height/2;});
+    if (centres.length && Math.max(...centres)-Math.min(...centres)>3) continue;
+    const rowBox=row.getBoundingClientRect();
+    const expected = centres.length ? centres.reduce((a,b)=>a+b,0)/centres.length : rowBox.y+rowBox.height/2;
+    for (const cell of row.children) {
+      if(!cell.matches('td,th') || !visible(cell)) continue;
+      // Editable rows compare their passive content to input centres. Record/action
+      // rows compare every complete content block, including multiline identities.
+      if(centres.length && cell.querySelector('input,textarea,select')) continue;
+      const boxes=[];
+      const walker=document.createTreeWalker(cell,NodeFilter.SHOW_TEXT);let textNode;
+      while((textNode=walker.nextNode())) {
+        if(!textNode.textContent?.trim() || !textNode.parentElement || !visible(textNode.parentElement)
+          || textNode.parentElement.closest('.flood-visually-hidden,[aria-hidden="true"],script,style')) continue;
+        const range=document.createRange();range.selectNodeContents(textNode);
+        boxes.push(...[...range.getClientRects()].filter(rect=>rect.width>0&&rect.height>0));
+      }
+      for(const control of [...cell.querySelectorAll('button,a.flood-link--button')].filter(visible)) boxes.push(control.getBoundingClientRect());
+      if(!boxes.length) continue;
+      const actual=(Math.min(...boxes.map(rect=>rect.top))+Math.max(...boxes.map(rect=>rect.bottom)))/2;
+      if(Math.abs(actual-expected)>3) addIssue({id:'table.mixed-row-centre',target:target(cell),offset:Math.round((actual-expected)*100)/100,message:centres.length
+        ? 'Cell content is offset from neighbouring input centres. Review resolved geometry.'
+        : 'Cell content is offset from the centre of a record/action row. Compare multiline identity, values and actions; use deliberate top alignment only when justified.'});
+    }
+  }
+  const actionNames=select('button.flood-button,a.flood-link--button').map(button=>(button.textContent||'').trim().replace(/\s+/g,' ').toLowerCase()).filter(name=>name.length>=4);
+  let wordsChecked=0;
+  const segmenters=new Map();
+  const canInspectWords=typeof Intl.Segmenter==='function';
+  if(canInspectWords)for(const cell of select('.flood-table th,.flood-table td')){
+    if(cell.matches('[data-wrap="anywhere"]'))continue;
+    const locale=cell.closest('[lang]')?.getAttribute('lang')||document.documentElement.lang||undefined;
+    if(!segmenters.has(locale)){
+      try{segmenters.set(locale,new Intl.Segmenter(locale,{granularity:'word'}));}
+      catch{segmenters.set(locale,new Intl.Segmenter(undefined,{granularity:'word'}));}
+    }
+    const walker=document.createTreeWalker(cell,NodeFilter.SHOW_TEXT);let node;
+    while((node=walker.nextNode())){
+      if(!node.parentElement||!visible(node.parentElement)||node.parentElement.closest('code,pre,.flood-inline-code,.flood-visually-hidden,[aria-hidden="true"]'))continue;
+      for(const word of segmenters.get(locale).segment(node.textContent||'')){
+        if(!word.isWordLike||word.segment.length<4)continue;
+        if(wordsChecked>=limit){truncated=true;break;}wordsChecked++;
+        if(word.segment.length>200)continue;
+        const range=document.createRange();range.setStart(node,word.index);range.setEnd(node,word.index+word.segment.length);
+        const boxes=[...range.getClientRects()].filter(rect=>rect.width>0&&rect.height>0);
+        if(boxes.length>1&&Math.max(...boxes.map(rect=>rect.y))-Math.min(...boxes.map(rect=>rect.y))>2){
+          addIssue({id:'table.word-fragment',target:target(cell),word:word.segment,message:'A word is split across rendered lines in a table cell. Review intrinsic column width and wrapping; deliberate technical or localized line breaking can be an exception.'});
+        }
+      }
+      if(wordsChecked>=limit)break;
+    }
+    if(wordsChecked>=limit){truncated=true;break;}
+  }
+  const grids=select('form [class]').filter(element=>{
+    if(element.closest('table') || getComputedStyle(element).display!=='grid')return false;
+    return [...element.children].filter(visible).length>=2 && element.querySelectorAll('input,select,textarea,[role="combobox"]').length>=2;
+  }).map(element=>{
+    const style=getComputedStyle(element),columns=style.gridTemplateColumns.match(/[\d.]+px/g)?.map(parseFloat)??[];
+    return {element,columns,gap:parseFloat(style.columnGap)||0,rect:element.getBoundingClientRect()};
+  }).filter(grid=>grid.columns.length>=2);
+  const contentTracks=grid=>{
+    const owners='.flood-field,.flood-date-picker,.flood-date-field,.flood-time-field,.flood-date-range-field,.flood-date-time-picker';
+    const nodes=[...grid.element.querySelectorAll(owners)].filter(element=>visible(element)&&!element.closest('table')&&!element.parentElement?.closest(owners));
+    if(nodes.length>limit)truncated=true;
+    const tracks=[];
+    for(const element of nodes.slice(0,limit)){
+      const rect=element.getBoundingClientRect();
+      const track=tracks.find(item=>Math.abs(item.x-rect.x)<=1);
+      if(track){if(Math.abs(track.width-rect.width)>1)return null;}
+      else tracks.push({x:rect.x,width:rect.width});
+    }
+    if(tracks.length!==grid.columns.length)return null;
+    tracks.sort((a,b)=>a.x-b.x);
+    return {tracks,left:tracks[0].x,right:Math.max(...tracks.map(track=>track.x+track.width))};
+  };
+  for(const grid of grids)grid.content=contentTracks(grid);
+  for(let i=0;i<grids.length;i++)for(let j=i+1;j<grids.length;j++){
+    const a=grids[i],b=grids[j];
+    if(a.element.closest('form')!==b.element.closest('form'))continue;
+    if(a.element.contains(b.element)||b.element.contains(a.element))continue;
+    if(!(a.rect.bottom<=b.rect.top+1||b.rect.bottom<=a.rect.top+1))continue;
+    if(a.content&&b.content&&a.content.tracks.length===b.content.tracks.length&&Math.abs(a.content.left-b.content.left)<=1&&Math.abs(a.content.right-b.content.right)<=1){
+      const offset=Math.max(...a.content.tracks.map((track,index)=>Math.max(Math.abs(track.x-b.content.tracks[index].x),Math.abs(track.width-b.content.tracks[index].width))));
+      if(offset>1)addIssue({id:'forms.content-track-drift',target:target(b.element),related:target(a.element),offset:Math.round(offset*100)/100,message:'Stacked form groups share content edges but their actual field starts or widths differ. Review nested surface padding and shared track ownership; matching Grid props or outer boxes is insufficient.'});
+    }
+    if(Math.abs(a.rect.x-b.rect.x)>1||Math.abs(a.rect.width-b.rect.width)>1)continue;
+    const starts=grid=>grid.columns.map((_,index)=>grid.columns.slice(0,index).reduce((sum,width)=>sum+width,0)+index*grid.gap);
+    const left=starts(a),right=starts(b);
+    const drift=a.columns.length===b.columns.length?Math.max(...left.map((x,index)=>Math.abs(x-right[index]))):null;
+    if(drift===null||drift>1)addIssue({id:'forms.track-drift',target:target(b.element),related:target(a.element),...(drift===null?{}:{offset:Math.round(drift*100)/100}),message:'Stacked form grids share an outer frame but use different tracks. Review common gutters/group hierarchy or document why these contexts need different columns.'});
+  }
+  for(const element of select('h1,h2,h3,h4,h5,h6,.flood-type--helper,.flood-type--compact')) {
+    if(label(element)) {
+      copy.push(target(element));
+      if(!element.closest('button,a,label') && !element.matches('h1,h2,h3,h4,h5,h6')) {
+        if(!element.closest('.flood-field,.flood-fieldset,.flood-table,.flood-metric,.flood-status-indicator,.flood-file-meta,.flood-description-list,nav,article,dialog,[role="document"],[role="status"],[role="alert"],[role="alertdialog"],[role="dialog"]')) {
+          addIssue({id:'copy.unowned-support',target:target(element),message:'Supporting text sits outside a field, operation state, navigation or structured document. Identify the exact current decision it serves; remove implementation narration. Do not change typography or add a semantic wrapper merely to silence this observation.'});
+        }
+        const text=(element.textContent||'').trim().replace(/\s+/g,' ').toLowerCase();
+        if(actionNames.some(name=>text.includes(name))) addIssue({id:'copy.action-echo',target:target(element),message:'Supporting copy repeats a currently visible action label. Review whether it adds a necessary constraint or only narrates the control.'});
+      }
+    }
+  }
+  for(const element of select('.flood-field,fieldset,.flood-section')) {
+    const rect=element.getBoundingClientRect();
+    fields.push({...target(element),x:rect.x,y:rect.y,width:rect.width,height:rect.height});
+  }
+  return {schemaVersion:1, issues, copy, fields, truncated, notChecked:[
+    'Editorial necessity and accuracy require contextual review; copy inventory is not an editorial verdict.',
+    'Form grouping and column hierarchy require review of task relationships and visible geometry.',
+    'Only the currently rendered document state is inspected; portals outside a selected root, other pages, iframes and shadow roots are not traversed.',
+    'These observations do not certify accessibility, functional correctness or overall visual quality.',
+    ...(!canInspectWords?['Word fragmentation was not inspected because Intl.Segmenter is unavailable.']:[])
+  ]};
+}

package/manifest.json

@@ -2,6 +2,11 @@
   "schemaVersion": 1,
   "entry": "SKILL.md",
   "files": [
+    {
+      "source": "dist/catalog.json",
+      "target": "flood/catalog.json",
+      "kind": "catalog"
+    },
     {
       "source": "DESIGN.md",
       "target": "flood/DESIGN.md",
@@ -106,9 +111,44 @@
       "source": "references/flood-verification/SKILL.md",
       "target": ".agents/skills/flood-ui/references/flood-verification/SKILL.md",
       "kind": "skill"
+    },
+    {
+      "source": "references/knowledge.md",
+      "target": ".agents/skills/flood-ui/references/knowledge.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/flood-interface-content/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-interface-content/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/interface-content-examples.md",
+      "target": ".agents/skills/flood-ui/references/interface-content-examples.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/rendered-review.md",
+      "target": ".agents/skills/flood-ui/references/rendered-review.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/flood-hierarchy/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-hierarchy/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-records/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-records/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/record-decisions.md",
+      "target": ".agents/skills/flood-ui/references/record-decisions.md",
+      "kind": "reference"
     }
   ],
-  "version": "0.2.9",
+  "version": "0.2.10",
   "installedEntry": ".agents/skills/flood-ui/SKILL.md",
   "pathBase": "source is package-relative; target is relative to the host project root"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flood-md/agent",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",
@@ -13,12 +13,18 @@
     "DESIGN.md",
     "SKILL.md",
     "references",
+    "lib",
+    "dist",
+    "knowledge.json",
     "workflows.json",
     "rules.json",
     "manifest.json",
     "README.md"
   ],
   "exports": {
+    "./inspect": {"types":"./lib/inspect.d.ts","import":"./lib/inspect.mjs"},
+    ".": {"types":"./lib/index.d.ts","import":"./lib/index.mjs"},
+    "./dist/*": "./dist/*",
     "./DESIGN.md": "./DESIGN.md",
     "./SKILL.md": "./SKILL.md",
     "./manifest.json": "./manifest.json",

package/references/flood-composition/SKILL.md

@@ -10,6 +10,11 @@ components. Preserve their anatomy and behavior when improving a composition.
 Read the governing project instructions, matching declarations and relevant
 component guide first. This skill grants no additional permissions.
 
+When introducing visible interface text, apply the
+[interface content skill](../flood-interface-content/SKILL.md) before filling
+optional headings, descriptions or helper slots. Existing user-authored content
+is not permission to rewrite it during an unrelated layout correction.
+
 ## Choose the smallest existing owner
 
 Before changing JSX, identify the visible roles and their existing owners:
@@ -18,6 +23,31 @@ metadata, IconButton for an icon action, Dialog for modal behavior, Text/Heading
 for typography, and the appropriate form, list or table primitive for semantics.
 Check the actual installed exports and props; do not invent APIs from newer docs.
 
+Search the installed catalog by the role before settling on a low-level building
+block. Read the selected contract and compare a more specific owner when one
+exists: Metric for a labelled statistic; DatePicker for ordinary date selection
+with typing and a calendar, DateField for an explicitly entry-only interaction;
+StatusIndicator for a named state. Input type="date"
+invokes the browser's picker, not Flood's Calendar. Use it only for an explicit
+native-picker requirement or a documented limitation of the installed controls.
+Heading/Text remain valid for ordinary prose, not a default replacement for an
+available statistic component.
+
+Include layout and secondary interactions in that selection: Grid for repeated
+form tracks, Stack/Inline for related layout, AlertDialog for a discard/delete
+confirmation, and Alert/StatusIndicator for the appropriate feedback role.
+window.confirm/alert/prompt are browser UI, not Flood components. A small scope
+does not justify replacing an available owner with native UI or a parallel CSS
+grid. Keep native form, table and semantic document/shell elements where they
+supply structure; styling the host shell is different from reimplementing a
+provided layout or control. Document a genuine missing capability before using
+a project-owned adapter.
+
+Record the selected owner and any rejected match before implementing the surface.
+If discovery finds no suitable component, state the missing capability; do not
+claim that the library has no owner without checking. Keep this decision record
+in development notes, never as extra explanatory text in the product.
+
 - Reuse the matching component with its supported props and tokens.
 - If spacing or alignment is wrong, inspect both the primitive and the parent
   composition. Fix the owner of the relationship. Keep the primitive intact.

package/references/flood-data-display/SKILL.md

@@ -9,6 +9,15 @@ Use the installed component contracts and
 [composition workflow](../flood-composition/SKILL.md). Start with the content's
 relationships, not a wrapper around every piece of text.
 
+Keep visual/test fixtures separate from the host's working records unless sample
+data is explicitly part of the task. Do not seed a new user's persisted list with
+fictional business records just to fill a screen. Use isolated test state for
+populated screenshots and exercise the real empty state. When samples are required, identify their provenance in the test brief/README.
+A visible distinction is needed where it changes interpretation or action, such
+as sample records mixed with real records. Do not automatically add a permanent
+Demo badge to the shell of an explicitly requested isolated prototype; follow
+the interface-content workflow for contextual placement.
+
 - Table/DataTable preserve caption, headers, cell relationships and documented
   sorting/selection behavior. A footer represents a summary and should be
   visually distinguishable without relying on a heavy border everywhere.
@@ -23,6 +32,13 @@ relationships, not a wrapper around every piece of text.
 - Preserve native image alt/fallback semantics and aspect constraints. Decorative
   artwork should not duplicate an adjacent accessible identity.
 
+## Choose the information, not all available slots
+
+For record lists/details, apply the [records skill](../flood-records/SKILL.md)
+before filling metadata and actions. Identity, supporting context, lifecycle state,
+priority and timestamps have different purposes. Use Table/DataTable when users
+need several named comparisons; a trailing Inline of values is not a column model.
+
 ## Exercise data and geometry
 
 Test no records, one record, long/wrapping names, absent optional media/actions,
@@ -31,6 +47,22 @@ without inserting a second empty-state design or moving unrelated controls.
 Align file title/metadata and status/progress by their intended row relationship;
 do not hide a StatusIndicator dot or replace Progress with a custom track.
 
+For an editable table, compare the centre of plain amounts and row actions with
+the neighbouring input controls. Table centres record/action and editable rows
+by default; opt into cellVerticalAlign="top" only for deliberate prose alignment.
+Use the shared cellVerticalAlign contract rather than
+moving text with transforms or overriding Input, NumberInput or Button internals.
+Native style on an individual host-owned td/th can express an exceptional cell.
+Do not depend on a low-specificity descendant CSS override. Check the rendered
+centres; equal cell padding alone does not establish alignment.
+
+Also inspect readable column widths with long neighbouring records. A centred
+cell can still be wrong when a status or date is fragmented into single letters.
+Table and StatusIndicator preserve word-based intrinsic width by default; keep
+that recipe rather than applying global overflow-wrap:anywhere. Deliberate
+technical identifier cells can opt into data-wrap="anywhere". Otherwise use
+local scrolling or appropriate column budgets, not an empty no-overflow claim.
+
 Use the documented local overflow owner, with a meaningful accessible name. Focus
 the last action/cell and check that a rail or rounded corner does not cover it.
 Compare narrow/wide, enlarged text and RTL. Locale-sensitive text in prerendered

package/references/flood-feedback/SKILL.md

@@ -10,6 +10,11 @@ visible role before choosing color: StatusIndicator names a state, Badge marks
 metadata, Progress describes task progress, Meter describes a bounded measurement,
 Alert gives contextual feedback and EmptyState explains missing content.
 
+For several record attributes, use the [records skill](../flood-records/SKILL.md).
+A category called Error is not a failed operation; priority is not lifecycle state.
+Choose the semantic owner before its appearance, and keep essential triage data
+visible even when reducing decorative emphasis.
+
 ## Keep one owner for each message
 
 - Status text must distinguish pending, success, failure, cancellation and local
@@ -24,13 +29,29 @@ Alert gives contextual feedback and EmptyState explains missing content.
 - Spinner retains a meaningful accessible label where standalone. Skeleton is
   decoration, not another announced task. Preserve the existing reduced-motion
   behavior without introducing a new animation system.
-- EmptyState needs a reason and an appropriate next action when available. Its
-  icon/illustration and action remain existing primitives with consistent geometry.
+- EmptyState identifies the actual condition. A title can be enough; add a
+  description only for new decision-relevant information, not an instruction
+  repeating a visible action. Its icon/action use existing primitives.
+
+## Scope feedback to its operation
+
+Associate a message with the operation and record that produced it. Preserve
+entered data after refusal and keep a useful error while that operation remains
+unresolved. A successful retry clears/replaces its failure. Explicitly discarding
+the draft ends that draft's save error; it must not follow the user to a list or
+another record. Ignore late results belonging to an abandoned operation.
+
+Do not solve this with an automatic timer inside Alert or by clearing every
+message on navigation. A collection-wide read failure can still block editing
+after changing views and must remain until resolved. The host's state model owns
+that distinction; the feedback primitive only presents the supplied state.
 
 ## Evidence
 
 Trigger the operation and observe each applicable transition, including failure
-and retry. Check optional description/action/icon slots, long messages and text
+and retry. Also follow failure → explicit discard → list → reopen a saved record;
+the abandoned draft's failure must be gone and the saved data unchanged. Distinguish
+that from a still-unresolved collection-wide error. Check optional description/action/icon slots, long messages and text
 enlargement. Keep content visible without stealing focus merely to announce it.
 Reserve feedback space in a demo when needed for a stable sample, not universally
 inside every production component. Report audible announcement behavior only