@fiyuu/core 0.1.0

package/src/responsive.js

@@ -0,0 +1,48 @@
+export const BREAKPOINTS = {
+    xs: 480,
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536,
+};
+export function mediaUp(name, css) {
+    return `@media (min-width:${BREAKPOINTS[name]}px){${css}}`;
+}
+export function mediaDown(name, css) {
+    return `@media (max-width:${BREAKPOINTS[name] - 0.02}px){${css}}`;
+}
+export function mediaBetween(min, max, css) {
+    return `@media (min-width:${BREAKPOINTS[min]}px) and (max-width:${BREAKPOINTS[max] - 0.02}px){${css}}`;
+}
+export function fluid(minSizePx, maxSizePx, minViewportPx = 360, maxViewportPx = 1440) {
+    if (maxViewportPx <= minViewportPx) {
+        throw new Error("fluid requires maxViewportPx to be larger than minViewportPx.");
+    }
+    const slope = ((maxSizePx - minSizePx) / (maxViewportPx - minViewportPx)) * 100;
+    const intercept = minSizePx - (slope / 100) * minViewportPx;
+    return `clamp(${minSizePx}px, ${intercept.toFixed(4)}px + ${slope.toFixed(4)}vw, ${maxSizePx}px)`;
+}
+export function responsiveSizes(config, fallback = "100vw") {
+    const ordered = Object.entries(BREAKPOINTS)
+        .sort((a, b) => b[1] - a[1])
+        .map(([name, width]) => {
+        const value = config[name];
+        if (!value)
+            return "";
+        return `(min-width: ${width}px) ${value}`;
+    })
+        .filter(Boolean);
+    ordered.push(fallback);
+    return ordered.join(", ");
+}
+export function responsiveStyle(selector, baseCss, overrides) {
+    const blocks = [`${selector}{${baseCss}}`];
+    for (const [name] of Object.entries(BREAKPOINTS)) {
+        const css = overrides[name];
+        if (!css)
+            continue;
+        blocks.push(mediaUp(name, `${selector}{${css}}`));
+    }
+    return `<style>${blocks.join("")}</style>`;
+}

package/src/scanner.d.ts

@@ -0,0 +1,65 @@
+declare const FIXED_FILES: readonly ["page.tsx", "action.ts", "query.ts", "schema.ts", "meta.ts"];
+export interface FeatureRecord {
+    route: string;
+    feature: string;
+    directory: string;
+    files: Partial<Record<(typeof FIXED_FILES)[number], string>>;
+    missingRequiredFiles: string[];
+    intent: string | null;
+    pageIntent: string | null;
+    descriptions: string[];
+    render: "ssr" | "csr" | "ssg";
+    warnings: string[];
+    /** Names of dynamic segments in order, e.g. ["id"] for /blog/[id] */
+    params: string[];
+    /** True if route has any dynamic [param] or [...slug] segments */
+    isDynamic: boolean;
+    /**
+     * Human-readable pattern string, e.g. "/blog/:id" or "/docs/:slug*"
+     * Stored for AI docs and devtools display only — not used for matching.
+     */
+    routePattern: string;
+}
+export interface ProjectGraph {
+    routes: Array<{
+        path: string;
+        feature: string;
+        hasPage: boolean;
+    }>;
+    actions: Array<{
+        route: string;
+        file: string;
+    }>;
+    queries: Array<{
+        route: string;
+        file: string;
+    }>;
+    schemas: Array<{
+        route: string;
+        file: string;
+        descriptions: string[];
+        render: "ssr" | "csr" | "ssg";
+    }>;
+    relations: Array<{
+        from: string;
+        to: string;
+        type: "uses" | "renders" | "describes";
+    }>;
+    features: FeatureRecord[];
+}
+export declare function scanApp(appDirectory: string): Promise<FeatureRecord[]>;
+export declare function createProjectGraph(appDirectory: string): Promise<ProjectGraph>;
+/**
+ * Parses dynamic segment syntax from a route string.
+ *
+ * Supported formats (mirrors Next.js conventions):
+ *   [param]         — single dynamic segment      /blog/[id]
+ *   [...slug]       — required catch-all           /docs/[...slug]
+ *   [[...slug]]     — optional catch-all           /docs/[[...slug]]
+ */
+export declare function parseRouteSegments(route: string): {
+    params: string[];
+    isDynamic: boolean;
+    routePattern: string;
+};
+export {};

package/src/scanner.js

@@ -0,0 +1,200 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const FIXED_FILES = ["page.tsx", "action.ts", "query.ts", "schema.ts", "meta.ts"];
+const REQUIRED_FILES = ["schema.ts", "meta.ts"];
+const SUPPLEMENTARY_FILES = ["middleware.ts", "layout.tsx", "layout.meta.ts", "route.ts", "not-found.tsx", "error.tsx"];
+const GENERATED_FILE_PATTERN = /\.(js|jsx|d\.ts|map)$/;
+export async function scanApp(appDirectory) {
+    const features = await walkFeatureDirectories(appDirectory);
+    const records = await Promise.all(features.map((directory) => scanFeature(appDirectory, directory)));
+    return records.sort((left, right) => left.route.localeCompare(right.route));
+}
+export async function createProjectGraph(appDirectory) {
+    const features = await scanApp(appDirectory);
+    return {
+        routes: features.map((feature) => ({
+            path: feature.route,
+            feature: feature.feature,
+            hasPage: Boolean(feature.files["page.tsx"]),
+        })),
+        actions: features
+            .filter((feature) => feature.files["action.ts"])
+            .map((feature) => ({ route: feature.route, file: feature.files["action.ts"] })),
+        queries: features
+            .filter((feature) => feature.files["query.ts"])
+            .map((feature) => ({ route: feature.route, file: feature.files["query.ts"] })),
+        schemas: features
+            .filter((feature) => feature.files["schema.ts"])
+            .map((feature) => ({
+            route: feature.route,
+            file: feature.files["schema.ts"],
+            descriptions: feature.descriptions,
+            render: feature.render,
+        })),
+        relations: features.flatMap((feature) => {
+            const relations = [];
+            if (feature.files["schema.ts"]) {
+                relations.push({ from: feature.route, to: feature.files["schema.ts"], type: "uses" });
+            }
+            if (feature.files["action.ts"]) {
+                relations.push({ from: feature.route, to: feature.files["action.ts"], type: "uses" });
+            }
+            if (feature.files["query.ts"]) {
+                relations.push({ from: feature.route, to: feature.files["query.ts"], type: "uses" });
+            }
+            if (feature.files["page.tsx"]) {
+                relations.push({ from: feature.route, to: feature.files["page.tsx"], type: "renders" });
+            }
+            if (feature.files["meta.ts"]) {
+                relations.push({ from: feature.route, to: feature.files["meta.ts"], type: "describes" });
+            }
+            return relations;
+        }),
+        features,
+    };
+}
+async function walkFeatureDirectories(root) {
+    const directories = [];
+    await visit(root, directories, root);
+    return directories;
+}
+async function visit(currentDirectory, directories, appDirectory) {
+    const entries = await fs.readdir(currentDirectory, { withFileTypes: true });
+    const fileNames = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+    const hasFeatureFiles = FIXED_FILES.some((fileName) => fileNames.has(fileName));
+    if (hasFeatureFiles) {
+        directories.push(currentDirectory);
+    }
+    await Promise.all(entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => visit(path.join(currentDirectory, entry.name), directories, appDirectory)));
+}
+/**
+ * Parses dynamic segment syntax from a route string.
+ *
+ * Supported formats (mirrors Next.js conventions):
+ *   [param]         — single dynamic segment      /blog/[id]
+ *   [...slug]       — required catch-all           /docs/[...slug]
+ *   [[...slug]]     — optional catch-all           /docs/[[...slug]]
+ */
+export function parseRouteSegments(route) {
+    const params = [];
+    const patternParts = route
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => {
+        const optionalCatchAll = segment.match(/^\[\[\.\.\.(\w+)\]\]$/);
+        if (optionalCatchAll) {
+            params.push(optionalCatchAll[1]);
+            return `:${optionalCatchAll[1]}?*`;
+        }
+        const catchAll = segment.match(/^\[\.\.\.(\w+)\]$/);
+        if (catchAll) {
+            params.push(catchAll[1]);
+            return `:${catchAll[1]}*`;
+        }
+        const dynamic = segment.match(/^\[(\w+)\]$/);
+        if (dynamic) {
+            params.push(dynamic[1]);
+            return `:${dynamic[1]}`;
+        }
+        return segment;
+    });
+    return {
+        params,
+        isDynamic: params.length > 0,
+        routePattern: `/${patternParts.join("/")}`,
+    };
+}
+async function scanFeature(appDirectory, featureDirectory) {
+    const relativeDirectory = path.relative(appDirectory, featureDirectory);
+    const feature = relativeDirectory.split(path.sep).join("/");
+    const route = `/${feature}`;
+    const files = Object.fromEntries(await Promise.all(FIXED_FILES.map(async (fileName) => {
+        const filePath = path.join(featureDirectory, fileName);
+        try {
+            await fs.access(filePath);
+            return [fileName, normalizePath(filePath)];
+        }
+        catch {
+            return [fileName, undefined];
+        }
+    })));
+    const metaSource = files["meta.ts"] ? await fs.readFile(path.join(featureDirectory, "meta.ts"), "utf8") : "";
+    const pageSource = files["page.tsx"] ? await fs.readFile(path.join(featureDirectory, "page.tsx"), "utf8") : "";
+    const schemaSource = files["schema.ts"] ? await fs.readFile(path.join(featureDirectory, "schema.ts"), "utf8") : "";
+    const featureEntries = await fs.readdir(featureDirectory, { withFileTypes: true });
+    const extraFiles = featureEntries
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .filter((fileName) => !FIXED_FILES.includes(fileName) &&
+        !SUPPLEMENTARY_FILES.includes(fileName) &&
+        !GENERATED_FILE_PATTERN.test(fileName));
+    const warnings = [
+        ...REQUIRED_FILES.filter((fileName) => !files[fileName]).map((fileName) => `Missing required file: ${fileName}`),
+        ...extraFiles.map((fileName) => `Non-standard file in feature directory: ${fileName}`),
+    ];
+    if (pageSource.length > 0) {
+        if (/<img\b/i.test(pageSource)) {
+            warnings.push("Raw <img> usage detected. Prefer optimizedImage() for lazy loading and responsive sources.");
+            if (countMatches(pageSource, /<img\b(?![^>]*\balt\s*=)[^>]*>/gi) > 0) {
+                warnings.push("Some <img> tags are missing alt attributes.");
+            }
+            if (countMatches(pageSource, /<img\b(?![^>]*\bloading\s*=)[^>]*>/gi) > 0) {
+                warnings.push("Some <img> tags are missing loading attribute (use loading=\"lazy\" when appropriate).");
+            }
+            if (countMatches(pageSource, /<img\b(?![^>]*\b(?:width|height)\s*=)[^>]*>/gi) > 0) {
+                warnings.push("Some <img> tags are missing intrinsic width/height which can cause layout shift.");
+            }
+        }
+        if (/<video\b/i.test(pageSource)) {
+            warnings.push("Raw <video> usage detected. Prefer optimizedVideo() for preload and source hints.");
+            if (countMatches(pageSource, /<video\b(?![^>]*\bpreload\s*=)[^>]*>/gi) > 0) {
+                warnings.push("Some <video> tags are missing preload strategy (recommended: preload=\"metadata\").");
+            }
+            if (countMatches(pageSource, /<video\b(?![^>]*\bposter\s*=)[^>]*>/gi) > 0) {
+                warnings.push("Some <video> tags are missing poster image, which hurts perceived loading performance.");
+            }
+        }
+    }
+    const { params, isDynamic, routePattern } = parseRouteSegments(route);
+    return {
+        route,
+        feature,
+        directory: normalizePath(featureDirectory),
+        files,
+        missingRequiredFiles: REQUIRED_FILES.filter((fileName) => !files[fileName]),
+        intent: extractStringValue(metaSource, "intent"),
+        pageIntent: extractStringValue(pageSource, "intent"),
+        descriptions: extractStringList(schemaSource, "description"),
+        render: extractRenderMode(metaSource),
+        warnings,
+        params,
+        isDynamic,
+        routePattern,
+    };
+}
+function extractStringValue(source, key) {
+    const match = source.match(new RegExp(`${key}\\s*(?::|=)\\s*["'\`]([^"'\`]+)["'\`]`));
+    return match?.[1] ?? null;
+}
+function extractStringList(source, key) {
+    return Array.from(source.matchAll(new RegExp(`${key}\\s*(?::|=)\\s*["'\`]([^"'\`]+)["'\`]`, "g"))).map((match) => match[1]);
+}
+function normalizePath(filePath) {
+    return filePath.split(path.sep).join("/");
+}
+function countMatches(source, pattern) {
+    const matches = source.match(pattern);
+    return matches ? matches.length : 0;
+}
+function extractRenderMode(source) {
+    const render = extractStringValue(source, "render");
+    if (render === "csr") {
+        return "csr";
+    }
+    if (render === "ssg") {
+        return "ssg";
+    }
+    return "ssr";
+}

package/src/state.d.ts

@@ -0,0 +1 @@
+export { createFiyuuStore, type FiyuuStore } from "./reactive.js";

package/src/state.js

@@ -0,0 +1 @@
+export { createFiyuuStore } from "./reactive.js";

package/src/template.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Embeds server-side data as a JSON script tag for client access via fiyuu.data(id).
+ *
+ * @example
+ * // In page.tsx template:
+ * ${clientData('my-posts', posts.map(p => ({ id: p.id, title: p.title })))}
+ *
+ * // In inline script:
+ * const posts = fiyuu.data('my-posts');
+ */
+export declare function clientData<T>(id: string, data: T): string;
+/**
+ * RawHtml — marks a string as already-safe HTML (bypasses auto-escaping).
+ */
+export declare class RawHtml {
+    readonly value: string;
+    constructor(value: string);
+    toString(): string;
+}
+/**
+ * Marks a string as trusted HTML (bypasses auto-escaping).
+ */
+export declare function raw(value: string | RawHtml): RawHtml;
+/**
+ * Alias for raw() — more explicit about intent.
+ */
+export declare const unsafeHtml: typeof raw;
+/**
+ * Internal HTML escaping — used by media.ts and responsive-wrapper.ts.
+ * Not intended for direct user consumption; html`` auto-escapes.
+ */
+export declare function escapeHtml(value: unknown): string;
+/**
+ * Tagged template for building HTML strings.
+ *
+ * All interpolations are auto-escaped by default (XSS-safe).
+ * Use raw() or unsafeHtml() for intentional raw HTML.
+ * null / undefined / false render as empty string.
+ * Arrays are auto-flattened and joined.
+ *
+ * @example
+ * html`<p>${user.bio}</p>`                    // auto-escaped
+ * html`<div>${unsafeHtml(someHtml)}</div>`    // intentional raw HTML
+ * html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`  // auto-flattened
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): string;
+export type ComponentProps = Record<string, unknown>;
+export declare function component<Props extends ComponentProps = ComponentProps>(render: (props: Props) => string): (props: Props) => string;

package/src/template.js

@@ -0,0 +1,98 @@
+/**
+ * Embeds server-side data as a JSON script tag for client access via fiyuu.data(id).
+ *
+ * @example
+ * // In page.tsx template:
+ * ${clientData('my-posts', posts.map(p => ({ id: p.id, title: p.title })))}
+ *
+ * // In inline script:
+ * const posts = fiyuu.data('my-posts');
+ */
+export function clientData(id, data) {
+    return `<script type="application/json" id="${id}">${JSON.stringify(data)}</script>`;
+}
+/**
+ * RawHtml — marks a string as already-safe HTML (bypasses auto-escaping).
+ */
+export class RawHtml {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    toString() {
+        return this.value;
+    }
+}
+/**
+ * Marks a string as trusted HTML (bypasses auto-escaping).
+ */
+export function raw(value) {
+    return value instanceof RawHtml ? value : new RawHtml(value);
+}
+/**
+ * Alias for raw() — more explicit about intent.
+ */
+export const unsafeHtml = raw;
+/**
+ * Internal HTML escaping — used by media.ts and responsive-wrapper.ts.
+ * Not intended for direct user consumption; html`` auto-escapes.
+ */
+export function escapeHtml(value) {
+    const text = value == null ? "" : String(value);
+    return text
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function autoEscape(value) {
+    if (value instanceof RawHtml) {
+        return value.value;
+    }
+    const text = value == null ? "" : String(value);
+    return text
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * Tagged template for building HTML strings.
+ *
+ * All interpolations are auto-escaped by default (XSS-safe).
+ * Use raw() or unsafeHtml() for intentional raw HTML.
+ * null / undefined / false render as empty string.
+ * Arrays are auto-flattened and joined.
+ *
+ * @example
+ * html`<p>${user.bio}</p>`                    // auto-escaped
+ * html`<div>${unsafeHtml(someHtml)}</div>`    // intentional raw HTML
+ * html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`  // auto-flattened
+ */
+export function html(strings, ...values) {
+    let output = "";
+    for (let index = 0; index < strings.length; index += 1) {
+        output += strings[index] ?? "";
+        if (index < values.length) {
+            output += serializeTemplateValue(values[index]);
+        }
+    }
+    return output;
+}
+function serializeTemplateValue(value) {
+    if (value == null || value === false) {
+        return "";
+    }
+    if (value instanceof RawHtml) {
+        return value.value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(serializeTemplateValue).join("");
+    }
+    return autoEscape(value);
+}
+export function component(render) {
+    return render;
+}

package/src/virtual.d.ts

@@ -0,0 +1,14 @@
+export interface VirtualListProps {
+    items: unknown[];
+    itemHeight: number;
+    height: number;
+    renderItem: (item: unknown, index: number) => string;
+}
+/**
+ * renderVirtualList — server-side HTML generator for virtualized lists.
+ *
+ * On the server all items are rendered (no real windowing). Client-side
+ * virtualization can be layered on top by reading the `data-fiyuu-virtual`
+ * attribute and the `data-item-height` / `data-total-height` values.
+ */
+export declare function renderVirtualList(props: VirtualListProps): string;

package/src/virtual.js

@@ -0,0 +1,21 @@
+import { html } from "./template.js";
+/**
+ * renderVirtualList — server-side HTML generator for virtualized lists.
+ *
+ * On the server all items are rendered (no real windowing). Client-side
+ * virtualization can be layered on top by reading the `data-fiyuu-virtual`
+ * attribute and the `data-item-height` / `data-total-height` values.
+ */
+export function renderVirtualList(props) {
+    const { items, itemHeight, height, renderItem } = props;
+    const totalHeight = items.length * itemHeight;
+    const itemsHtml = items
+        .map((item, index) => `<div style="height:${itemHeight}px;overflow:hidden">${renderItem(item, index)}</div>`)
+        .join("");
+    return html `<div
+    data-fiyuu-virtual
+    data-item-height="${itemHeight}"
+    data-total-height="${totalHeight}"
+    style="height:${height}px;overflow-y:auto;position:relative"
+  ><div style="height:${totalHeight}px;position:relative">${itemsHtml}</div></div>`;
+}